Troubleshooting

Configuration fails

Run zagent doctor. Check PROVIDER, BASE_URL, MODEL, credentials, and config.json. Unknown configuration keys are rejected. The provider may require a specific model ID or endpoint path.

Commands are refused

The default permissions.run_command="ask" refuses execution because interactive approval is not implemented in the normal interfaces. If your trusted, isolated workflow requires shell access, deliberately configure allow. It runs with your user permissions. See security.

A tool is missing

Run zagent tools list. Check tools.enabled, tools.disabled, manifest filename, schema, and platforms. External tools are loaded at session start; start a fresh session after installing one. Install any interpreter that tool requires.

A tool returns invalid JSON

With output: "json", stdout must contain one JSON object. Send diagnostic logs to stderr. Test the exact call with zagent tools run NAME --args JSON; this developer command auto-grants tool approval requests.

Attachment is rejected

Check .env media capabilities, the endpoint's supported input types, tools.max_attach_mb, and request body limits. A provider that supports images does not necessarily support PDF, audio, or video through the selected API format.

Request is too large

The engine can prune old attachments and compact history. Lower context.request_body_limit_mb if your gateway has a lower limit. Use smaller inputs or a fresh session if summary quality or attachment retention matters.

Network trouble or a stalled stream

Check connectivity and provider status, then inspect network retry settings. /resume retries immediately during a pause. An early clean stream disconnect can be accepted as completed in v0.1.1; verify the result before using it.

Session is busy

Attach to its running engine using the same --session NAME. Do not remove ownership files to force another writer. If the process has ended, OS ownership is released; discovery metadata may take a moment to settle.

The browser or terminal disconnected

The task may still be running. Reopen the interface with the session name. Reconnection is limited in this preview. Use the authenticated local API or inspect a stopped session to establish the current state.

Windows or macOS blocks the binary

The preview binaries are unsigned and macOS builds are not notarized. Verify the checksum and follow your organization's application-approval process. Do not disable platform protection globally.

Reporting a problem

Record the binary version, OS/architecture, provider format, command, and a minimal reproduction. Include redacted error text and expected behavior. Remove credentials, client data, process tokens, and sensitive attachment paths before sharing diagnostics with your Zyreca contact.