Error Codes
Canopy error codes appear in CLI output and log files. Each code has a category prefix.
Process exit codes
Section titled “Process exit codes”| Code | Meaning |
|---|---|
0 | Success. |
| non-zero | Failure; the error message is printed to stderr. |
2 | --no-network violation — a cloud-backend configuration was detected while the “nothing leaves the box” assertion was active (--no-network on index, serve, doctor, update, or CANOPY_NO_NETWORK=1). Also returned for usage errors such as naming the same step in both canopy setup --only and --skip. |
canopy ci exits non-zero when P0 findings are present (see --fail-on-p0).
License Errors
Section titled “License Errors”InvalidFormat
Section titled “InvalidFormat”Message: invalid license key format — expected <payload>.<signature>
Cause: The key string passed to canopy activate does not contain a . separator, or one of the two base64 components is empty.
Fix: Copy the full license key from your purchase email. The key is a long string containing exactly one . separator between the base64 payload and the signature. Do not add spaces or line breaks.
InvalidSignature
Section titled “InvalidSignature”Message: signature verification failed — key may be tampered or forged
Cause: The Ed25519 signature does not match the payload. The key was either corrupted during copy-paste, modified, or was issued by a different key pair.
Fix: Re-copy the license key directly from the original purchase email. If the key still fails, contact support — your key may need to be reissued.
Expired
Section titled “Expired”Message: license expired on <date>
Cause: The license expiration date has passed.
Fix: Renew your subscription at https://canopy.gulfshieldtech.com/pricing. After renewal, you will receive a new license key. Run canopy activate <new-key> to install it.
MachineLimitReached
Section titled “MachineLimitReached”Message: machine limit reached — deactivate an existing machine first
Cause: You have reached the machine binding limit for your tier (Solo: 1 machine, Pro: 3 machines, Team: seat count).
Fix: On the machine you want to remove, run:
canopy deactivateThis releases the seat server-side; then activate on the new machine. Activating on a new machine when the limit is full also offers to evict a stale binding. Both paths are server-ledger operations only — the license key and its hash never change, and the license is never re-signed. If you no longer have access to the old machine, contact support to release the seat.
Revoked
Section titled “Revoked”Message: license revoked
Cause: The subscription was cancelled, a refund was issued, or a payment dispute was filed.
Fix: Check your subscription status. If the cancellation was unintentional, resubscribe at https://canopy.gulfshieldtech.com/pricing and activate the new key. For payment disputes, contact support.
UnknownVersion
Section titled “UnknownVersion”Message: unknown license schema version <N> — please update Canopy
Cause: The license payload uses a schema version higher than this binary supports.
Fix: Update Canopy to the latest version:
canopy updateIndex Errors
Section titled “Index Errors”RepoNotFound
Section titled “RepoNotFound”Message: repository not found at <path> — run canopy index <path> first
Cause: The specified repository path does not exist, or no index exists for it yet.
Fix:
canopy index <path>The full-text search index and embeddings are built by default.
IndexCorrupted
Section titled “IndexCorrupted”Message: index database is corrupted — re-index required
Cause: The index database is corrupt (truncated write, filesystem error, or interrupted index).
Fix: Run a full re-index to rebuild from scratch:
canopy index <path> --fullDatabaseLocked
Section titled “DatabaseLocked”Message: index database is locked by another process
Cause: Another canopy serve or canopy index process is currently running and holds the SQLite write lock.
Fix: Check for other running Canopy processes:
ps aux | grep canopyStop the other process, then retry.
Search & Embedding Errors
Section titled “Search & Embedding Errors”SearchIndexMissing
Section titled “SearchIndexMissing”Cause: The Tantivy full-text search index does not exist for this repository — the index was built with --no-search (the search index is built by default and powers canopy answer’s keyword, pattern, and semantic recipes).
Fix:
canopy index <path>Alternatively, canopy serve --answer bootstraps the full-text index in the background if it is missing.
EmbeddingProviderUnavailable
Section titled “EmbeddingProviderUnavailable”Message: embedding provider unavailable — semantic search disabled
Cause: Semantic recipes require an embedding provider: the bundled local ONNX model (auto-fetched on first use when online) or Ollama. Either the provider is not running or the model has not been installed.
Fix:
canopy setup --only embeddingcanopy index <path>canopy setup installs and configures Ollama and the embedding model; --bundle-path installs offline. Embedding failure is always non-fatal — keyword recipes continue to work without embeddings.
Health Errors
Section titled “Health Errors”PluginParseError
Section titled “PluginParseError”Message: plugin <id> could not be parsed: <yaml error>
Cause: A file in .canopy/plugins/ contains invalid YAML syntax.
Fix: Open the indicated plugin file and fix the YAML syntax error. The health runtime picks up the corrected pack on the next canopy index or canopy ci run.
PluginPatternError
Section titled “PluginPatternError”Message: plugin <id> pattern is invalid: <pattern error>
Cause: The pattern field in a plugin file is not valid ast-grep syntax.
Fix: Review the pattern in the indicated plugin file. Common mistakes:
- Unclosed
$wildcards (use$VAR, not$) - Language-specific syntax that ast-grep does not support
- Patterns that only make sense in one language applied to another
See Plugin API for pattern syntax reference.
Network Errors
Section titled “Network Errors”HeartbeatFailed
Section titled “HeartbeatFailed”Message: heartbeat: failed — <reason> (non-fatal)
Cause: The weekly heartbeat POST failed. Common reasons: no network connectivity, firewall blocking outbound HTTPS, or the endpoint is temporarily unavailable.
Effect: Non-fatal. The cached license result is used and Canopy continues normally.
Fix: Check network connectivity, then inspect or retry via canopy config heartbeat. See Heartbeat Protocol.
UpdateCheckFailed
Section titled “UpdateCheckFailed”Message: update check failed: <reason>
Cause: canopy update --check could not reach the release manifest at https://downloads.canopy.gulfshieldtech.com.
Effect: Non-fatal. Your current version continues to work.
Fix: Check network connectivity and retry. Note that canopy update refuses to run under --no-network (exit code 2).
CI Errors
Section titled “CI Errors”CiFormatUnknown
Section titled “CiFormatUnknown”Cause: The --format flag passed to canopy ci is not one of the supported values: github, gitlab, sarif, json, or auto.
Fix:
canopy ci --format githubcanopy ci --format auto # detect from CI environment variablesCiLicenseRequired
Section titled “CiLicenseRequired”Message: canopy ci requires a Pro tier license or higher
Cause: canopy ci was invoked without a Pro or Team license.
Fix: Upgrade to Pro or Team tier at https://canopy.gulfshieldtech.com/pricing. For CI environments, provide the license key via environment variable:
export CANOPY_LICENSE_KEY="<your-key>"canopy ci --repo .Answer-Path Behaviors
Section titled “Answer-Path Behaviors”These are deliberate canopy_answer / canopy answer outcomes, not errors.
Honest no-match
Section titled “Honest no-match”When nothing clears the relevance floor (cross-encoder-calibrated), the answer is “No strong match in this repository for …” instead of a relay of tangential files. An empty answer is signal, not noise — do not retry the identical question expecting different results; rephrase with a more specific question shape.
Internal call budget
Section titled “Internal call budget”canopy_answer caps internal tool-handler calls per question via the max_internal_calls parameter (default 3, max 8). Raise the cap for questions that need deeper traversal.