Error Codes

Forge error codes appear in CLI output, MCP tool responses, and log files. Each code has a category prefix.

License Errors

`InvalidFormat`

Message: invalid license key format — expected <payload>.<signature>

Cause: The key string passed to forge 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`

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 (e.g., a dev key used in a production binary).

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`

Message: license expired on <date>

Cause: The license expiration date has passed.

Fix: Renew your subscription at https://forge.ironpinelabs.com/pricing. After renewal, you will receive a new license key. Run forge activate <new-key> to install it.

`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). Forge tracks machines by SHA-256 of hostname, MAC address, CPU brand, and machine ID.

Fix: On the machine you want to remove, run:

forge deactivate

Then activate on the new machine. If you no longer have access to the old machine (lost or replaced), contact support to release the machine slot.

`Revoked`

Message: license revoked

Cause: The subscription was cancelled, a refund was issued, or a payment dispute was filed.

Fix: Check your Stripe subscription status. If the cancellation was unintentional, resubscribe at https://forge.ironpinelabs.com/pricing and activate the new key. For payment disputes, contact support.

`UnknownVersion`

Message: unknown license schema version <N> — please update Forge

Cause: The license payload uses a schema version higher than this binary supports.

Fix: Update Forge to the latest version:

forge update

Index Errors

`RepoNotFound`

Message: repository not found at <path> — run forge index <path> first

Cause: The specified repository path does not exist, or no index exists for it yet.

Fix:

forge index <path> --with-search

`IndexCorrupted`

Message: index database is corrupted — re-index required

Cause: The SQLite database at ~/.forge/<repo-hash>/forge.db is corrupt (truncated write, filesystem error, or interrupted index).

Fix: Run a full re-index to rebuild from scratch:

forge index <path> --full --with-search

`DatabaseLocked`

Message: index database is locked by another process

Cause: Another forge serve or forge index process is currently running and holds the SQLite write lock.

Fix: Check for other running Forge processes:

ps aux | grep forge

Stop the other process, then retry. If no other process is running, the lock file may be stale from a crashed process. Delete ~/.forge/<repo-hash>/forge.db-wal and ~/.forge/<repo-hash>/forge.db-shm and retry.

Search Errors

`SearchIndexMissing`

Message: search index not found — run forge index --with-search first

Cause: The Tantivy full-text search index does not exist for this repository. forge index was run without --with-search.

Fix:

forge index <path> --with-search

This adds the search index without losing the existing AST index.

`EmbeddingProviderUnavailable`

Message: embedding provider unavailable — semantic search disabled

Cause: Semantic search requires an embedding provider (Ollama or ONNX Runtime). Either the provider is not running, or the model has not been downloaded.

Fix: For Ollama:

forge setup
forge index <path> --with-search --with-embeddings

For ONNX Runtime:

forge warmup-model
forge index <path> --with-search --with-embeddings

Keyword-only search (forge_search without semantic mode) continues to work even when embeddings are unavailable.

Health Errors

`PluginParseError`

Message: plugin <id> could not be parsed: <yaml error>

Cause: A file in .forge/plugins/ contains invalid YAML syntax.

Fix: Open the indicated plugin file and fix the YAML syntax error. Run forge health again — the error message includes the line and column of the first syntax problem.

`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

`HeartbeatFailed`

Message: heartbeat: failed — <reason> (non-fatal)

Cause: The weekly heartbeat POST to the Cloudflare Worker failed. Common reasons: no network connectivity, firewall blocking outbound HTTPS, or the Worker endpoint is temporarily unavailable.

Effect: Non-fatal. The cached license result is used. Forge continues normally until the cache becomes stale (>30 days) or very stale (>60 days).

Fix: Check network connectivity. Force a retry when connectivity is restored:

forge config heartbeat now

`UpdateCheckFailed`

Message: update check failed: <reason>

Cause: forge update --check could not reach the update manifest at https://downloads.forge.ironpinelabs.com/latest.json.

Effect: Non-fatal. Your current version continues to work.

Fix: Check network connectivity and retry. If the error persists, visit https://forge.ironpinelabs.com to check for updates manually.

CI Errors

`CiFormatUnknown`

Message: unknown CI format: <format> — expected github, gitlab, azure, or auto

Cause: The --format flag passed to forge ci is not one of the supported values.

Fix: Use one of the supported formats:

forge ci --format github
forge ci --format auto   # auto-detects from CI environment variables

`CiLicenseRequired`

Message: forge ci requires a Pro tier license or higher

Cause: forge ci was invoked without a Pro or Team license.

Fix: Upgrade to Pro or Team tier at https://forge.ironpinelabs.com/pricing. For CI environments, provide the license key via environment variable:

export FORGE_LICENSE_KEY="<your-key>"
forge ci --repo .