Chukke documentation

Troubleshooting

Resolve common workspace, analysis, provider, export, and recovery problems.

Start by preserving the workspace document involved. Chukke uses plain files, so you can inspect or copy the document with Finder or another editor before troubleshooting.

A recent workspace will not open

The folder may have moved, been deleted, become inaccessible, or need authorization again.

  1. Confirm the folder still exists in Finder.
  2. Use the Chukke reauthorization flow to select it again.
  3. If you cancel reauthorization, the current workspace should remain unchanged.

Clearing Recents removes stored authorizations but does not delete workspace folders.

A recent file will not open

The document may have moved, been deleted, become unreadable, or need authorization again.

  1. Confirm the file still exists in Finder and has a supported .md, .markdown, or .txt extension.
  2. Use the Chukke locate-again flow to select the same document at its current location.
  3. If you cancel, the current workspace and open documents remain unchanged.

Removing a Recent Files entry deletes only Chukke’s authorization metadata. It does not delete the document.

Model-ready says the analysis is out of date

The document changed after the current analysis snapshot. Choose Refresh analysis, then review the reconciled findings before applying, copying, or using optional provider assistance.

A provider request fails

  1. If Chukke says the API key is missing, add it in Assist settings. No provider request was sent. Session-only keys must be entered again after restart; keys explicitly remembered in macOS Keychain normally return on this Mac. If Keychain access fails, enter the key for this session and retry remembering it later.
  2. If the provider did not accept the key, open Assist settings and check or replace it. Chukke cannot determine whether it expired.
  3. If the provider denied access, check your account and model permissions. For a rate limit or quota message, check the provider account or try later.
  4. For a connection or timeout message, check the provider URL and your network or VPN connection. For local Ollama, confirm the service is running and accessible.
  5. Other request errors remain in the request preview. Choose Try again only when ready to send the reviewed payload. After changing a key, start the action again and confirm its payload; Chukke does not retry automatically. The separate Settings connection test sends no document content and shows its result beside Test connection.

Provider availability and account errors are controlled by the provider, not by Model-ready. If a Settings connection test cannot look up the provider hostname, check the API URL and your network or VPN connection, then test again.

An export fails

Choose another destination you can write to and retry. Confirm the target filename is valid and that the destination is available. Export runs locally and does not require a provider connection.

Recover a previous version

Open the document’s History panel, inspect the available snapshots and diff, then restore the version you choose. Remember that local history is bounded and is not a complete backup.

Collect support information

Use Help > Report an Issue… to create a reviewable draft. Adding sanitized diagnostics is optional. Inspect the saved ZIP before attaching it, then send only when you approve the email contents.