Troubleshooting and FAQ

Common errors and what to do about them. If something is not covered here, email edward@zoniteai.com.

License and activation

"That license key doesn't look valid"

The key is checked locally, including a checksum, so a mistyped or incomplete key is rejected immediately. Copy the key exactly as it appears in your purchase email. You do not need to fix formatting: lowercase, spaces, line breaks, and odd dashes are corrected automatically. Note that the key alphabet never contains 0, O, 1, or I; if you are retyping by hand and see one of those, it is a different character. Still rejected: reply to your purchase email or write to support.

"Activate your license in Settings to use AI features"

AI generation is gated behind activation. Enter your key under Settings, License. All deterministic features keep working without it.

Key accepted but could not be saved

If activation reports that the key was accepted but could not be written to secure storage, macOS blocked Keychain access. Quit and reopen the app, try again, and allow access if macOS asks. Settings also shows a "Check again" button when secure storage is unreachable. An unreachable Keychain is treated as an error state, not as "unlicensed", so your activation is not lost.

AI errors

"Configure your AI API key in Settings first"

No API key is stored. Add one under Settings, AI Configuration. See AI setup. If a key is stored but Settings warns that it was saved for the other provider (OpenAI keys start with sk-, Anthropic keys with sk-ant-), replace it with a key for the selected provider.

"AI Account Out of Credit" versus "Rate Limit Exceeded"

The app distinguishes these two, because one is fixed with billing and the other with patience:

• Out of credit is a billing problem on your provider account, and retrying will not help. Add credit or update billing: OpenAI under Billing at platform.openai.com, Anthropic under Plans & Billing at console.anthropic.com.
• Rate limit means too many requests in a short window. Wait 30 to 60 seconds and try again. The app already retries transient provider errors up to three times on its own before showing you this.

"The response was cut off. Consider a smaller scope"

The model hit its output limit. Narrow the request: in Scout, ask a more specific question; in Documentation, regenerate the affected sections individually rather than the whole set. If the app reports that the model spent its entire budget on reasoning, switch to a different model or reduce the scope further.

"The AI API key is missing or invalid"

The provider rejected the key. Check that it is entered correctly in Settings and still active in your provider's dashboard; revoked or expired keys fail this way. The app does not test the key when you save it, so a bad key first surfaces on the first generation.

The request timed out or failed with a temporary error

Provider outages and overload happen. The app retries automatically; if it still fails, wait a minute and try again. Nothing is lost: your data is saved locally, and any sections generated before the failure are kept.

File uploads

A failed upload never damages existing data

Your current project data is only replaced after the new file parses successfully and yields at least one resource. Any parse error, and any upload with zero usable rows, leaves the project exactly as it was.

File rejected before parsing

• Only CSV, JSON, and Excel (.xlsx/.xls) are supported.
• Maximum file size is 10 MB.
• One file at a time; a second file replaces the first.

"No resources found in file"

The file parsed but contained no usable rows. Check that it has a header row plus at least one data row, and that some column identifies a resource name or type. An empty Azure export (for example, a filter that matched nothing) produces exactly this.

"This file uses an unsupported text encoding"

Re-save the file as UTF-8, or UTF-16 with a byte order mark. PowerShell's Export-Csv output is handled automatically because it includes the mark.

CSV or JSON parse errors

A CSV error pointing at a specific line is usually an unbalanced quote character in that row. An invalid JSON error usually means the export is truncated; re-export and check the file ends properly. If only some CSV rows are malformed, the app skips those rows, imports the rest, and tells you how many were skipped.

macOS specifics

Gatekeeper

The app is signed and notarized, so it opens without warnings. If macOS claims the app is damaged or from an unidentified developer, the download itself is likely corrupted or incomplete: delete the DMG and app, re-download from the website, and install again.

Keychain prompts

You should not normally see Keychain prompts; the signed app accesses its own Keychain items silently. If a prompt does appear, allow access, or the app cannot read your license and API key. See "Key accepted but could not be saved" above for the recovery path.

Exports and files

Where did my exported report go?

Wherever you chose in the save dialog. The Reports page in the Library lists every export with its full path, and can copy the path or reveal the file in Finder. If the Finder shortcut fails, the file was moved or deleted after export; the Reports page records where it was saved, it does not track the file afterwards. Topology PNG, PDF, and JSON exports are saved the same way but are not recorded on the Reports page.

FAQ