Troubleshooting

This page covers common issues you might encounter when using Kirby Copilot, along with solutions to get you back on track.

Long Generations Fail With JSON Parse Error

If you're generating longer content (300+ words) and see errors like No object generated: could not parse the response or JSON parsing failed: Unterminated string in JSON, the AI response is likely being cut off before it completes.

Starting with Copilot v3, all AI requests go through a server-side PHP proxy for security. This means your web server needs to keep the connection alive for the entire generation – which can take 60+ seconds for longer content. The culprit is usually a timeout at the web server level, not PHP itself.

Laravel Herd

Herd uses nginx with FastCGI, and the default fastcgi_read_timeout is 60 seconds – often too short for longer AI generations.

Add the following to your Herd nginx configuration at ~/Library/Application Support/Herd/config/nginx/herd.conf:

# Add inside the server { } block or the PHP location block
fastcgi_read_timeout 300;

Restart Herd after editing for the changes to take effect.

Laravel Valet (Standalone)

If you're using standalone Valet (not Herd), it also uses nginx with FastCGI. Edit your site-specific configuration in ~/.config/valet/Nginx/ and add fastcgi_read_timeout 300; to the PHP location block.

MAMP / MAMP Pro

MAMP uses Apache with mod_php by default, where PHP runs directly inside the Apache process. Since the Copilot proxy already disables PHP's execution timeout, no additional configuration should be needed.

If you still experience timeouts, check Apache's Timeout directive (default is 300 seconds).

Docker or Custom nginx

If you're running nginx in Docker or a custom setup, add the timeout directive to your PHP location block:

location ~ \.php$ {
    # ... existing FastCGI config ...
    fastcgi_read_timeout 300;
}

Production Environments

For deployed sites, the configuration depends on your hosting setup:

API Key Not Working

If requests fail with authentication errors or "Missing API key" messages, double-check your configuration:

1. Verify the API key is set in your config.php under the correct provider.
2. Make sure the provider name matches exactly: google, openai, anthropic, or mistral.
3. If you're using a closure for the API key, ensure it returns the key correctly.
4. Test the API key directly with the provider's API to rule out key issues.

'johannschopplich.copilot' => [
    'provider' => 'google',
    'providers' => [
        'google' => [
            'apiKey' => 'YOUR_API_KEY' // Verify this is valid
        ]
    ]
]

Blocks Generation Returns Empty or Malformed Content

When generating blocks or layouts, you might see empty results, missing fields, or incorrectly structured content. This usually comes down to the AI model's ability to handle nested JSON schemas.

A few things to try:

1. Switch to Google Gemini – it has the best support for structured output with nested schemas.
2. Simplify your prompt or generate fewer blocks at a time.
3. Check that your block blueprints have clear field definitions.
4. Enable debug logging to inspect the raw AI response:

'johannschopplich.copilot' => [
    'logLevel' => 'debug'
]

Inline Suggestions Not Appearing

If ghost text suggestions don't appear when typing in writer fields, check the following:

1. Make sure the copilot-suggestions mark is added to your writer field:

text:
  type: writer
  marks:
    - copilot-suggestions

2. Verify that completion is not disabled in your global configuration.