# Error codes

Every error has a stable code, a message and a fix. Codes are never translated.

## E_INTERNAL

HTTP 500 · exit 1

Something went wrong inside GenPM.

**Fix:** Retry with --verbose and report the issue with its requestId if it persists.

## E_BAD_REQUEST

HTTP 400 · exit 2

The request is invalid: …

**Fix:** Check the parameters and try again.

## E_USAGE

HTTP 400 · exit 2

Invalid usage: …

**Fix:** Run genpm --help to see the available options.

## E_CONFIRM_REQUIRED

HTTP 400 · exit 2

Confirmation needed: …

**Fix:** Run in an interactive terminal, or pass … to confirm.

## E_PAYLOAD_TOO_LARGE

HTTP 413 · exit 2

The request body is too large.

**Fix:** Send at most 16 KB.

## E_NOT_FOUND

HTTP 404 · exit 3

… was not found.

**Fix:** Check the spelling or search with genpm search <query>.

## E_NO_MATCHING_VERSION

HTTP 404 · exit 3

No version of … matches ….

**Fix:** Run genpm info … to see the published versions.

## E_DEST_CONFLICT

HTTP 409 · exit 4

… exists and is not empty.

**Fix:** Use --dest <dir> or --force (backs up first).

## E_RANGE_UNSATISFIED

HTTP 409 · exit 4

No version satisfies all ranges: …

**Fix:** Install a compatible version of the conflicting package first, or pin a different version.

## E_ALREADY_INSTALLED

HTTP 409 · exit 4

… … is already installed.

**Fix:** Nothing to do. Use genpm list to see installed packages.

## E_VERSION_EXISTS

HTTP 409 · exit 4

…@… has already been published.

**Fix:** Versions are immutable: bump the version in genpm.json and create a new tag.

## E_DRIFT

HTTP 409 · exit 4

… has local changes in ….

**Fix:** Use --keep-code to keep your code, or --force to delete it anyway.

## E_REQUIRED_BY

HTTP 409 · exit 4

… is required by ….

**Fix:** Remove the dependent packages first.

## E_BUSY

HTTP 409 · exit 4

Another GenPM process is modifying this project.

**Fix:** Wait for it to finish. If none is running, delete .genpm/.lock.

## E_PLAN_STALE

HTTP 409 · exit 4

The project changed since the plan was computed.

**Fix:** Compute the plan again (dry run) and confirm it.

## E_NETWORK

HTTP 502 · exit 5

Could not reach ….

**Fix:** Check your connection, proxy or GENPM_REGISTRY, then retry.

## E_UPSTREAM_GIT

HTTP 502 · exit 5

The Git host failed: …

**Fix:** Check that the repository is reachable with your Git credentials, then retry.

## E_RATE_LIMITED

HTTP 429 · exit 5

Too many requests.

**Fix:** Wait … and retry.

## E_READ_ONLY

HTTP 503 · exit 5

The registry is in read-only mode during maintenance.

**Fix:** Installing still works. Try publishing again later; status updates on genpm.net.

## E_INTEGRITY

HTTP 422 · exit 6

Integrity check failed for …: …

**Fix:** Do not use this package. Report it with genpm.net/report if it persists.

## E_SIGNATURE

HTTP 422 · exit 6

The registry signature of … is invalid.

**Fix:** Do not install it. Update GenPM (new signing keys) and report it if it persists.

## E_PATH_UNSAFE

HTTP 422 · exit 6

Unsafe path … (…).

**Fix:** Use a relative path inside the project, without .., absolute paths or reserved folders.

## E_AUTORUN_FILE

HTTP 422 · exit 6

… contains files that run automatically: ….

**Fix:** These files are never installed. Ask the author to remove them, or use --allow-autorun only for verified publishers.

## E_SCAN_FAILED

HTTP 422 · exit 6

The security scan rejected …: …

**Fix:** Fix the findings listed by genpm validate and publish a new version.

## E_INSECURE_PERMS

HTTP 400 · exit 6

… is readable by other users.

**Fix:** Run chmod 600 ….

## E_QUARANTINED

HTTP 451 · exit 6

… is under security review.

**Fix:** Try again later or choose another package. Reviews take less than 24 business hours.

## E_REF_MUTABLE

HTTP 422 · exit 6

… is not an immutable reference.

**Fix:** Use a Git tag or a full 40-character commit SHA, never a branch.

## E_ADVISORY

HTTP 409 · exit 6

… … has a … security advisory.

**Fix:** Update to … or later.

## E_TOO_LARGE

HTTP 422 · exit 6

… exceeds the size limit: …

**Fix:** Exclude files with .genpmignore, or raise the limit with --max-size if the package is legitimate.

## E_MANIFEST_INVALID

HTTP 422 · exit 6

genpm.json is invalid.

**Fix:** Fix the fields listed in the details. Run genpm validate for a full report.

## E_LOCK_INVALID

HTTP 422 · exit 6

genpm.lock is invalid or corrupted.

**Fix:** Restore it from Git; never edit genpm.lock by hand.

## E_NAME_MISMATCH

HTTP 422 · exit 6

The manifest name … does not match ….

**Fix:** Publish with the name declared in genpm.json.

## E_REF_NOT_FOUND

HTTP 422 · exit 3

… does not exist in ….

**Fix:** Create and push the tag: git tag … && git push --tags.

## E_REF_NOT_PUSHED

HTTP 422 · exit 4

… is not on the remote or points to another commit.

**Fix:** Push the tag with git push origin ….

## E_REPO_NOT_ALLOWED

HTTP 422 · exit 7

… is not owned by the scope @….

**Fix:** Publish from a repository of the GitHub owner linked to the scope.

## E_REPO_CHANGED

HTTP 422 · exit 6

The repository behind … changed (possible repojacking).

**Fix:** Email hello@genpm.net with subject [SECURITY] to transfer the package.

## E_CONTEXT_MISSING

HTTP 422 · exit 6

The AI rules file … does not exist.

**Fix:** Create … (genpm init generates a template) or set x in genpm.json.

## E_CONTEXT_TOO_LARGE

HTTP 422 · exit 6

The AI rules file … is larger than 16 KB.

**Fix:** Shorten it: keep the rules focused on purpose, map, integration, conventions and don'ts.

## E_AUTH

HTTP 401 · exit 7

You are not logged in, or your token is invalid or expired.

**Fix:** Run genpm login (or set GENPM_TOKEN in CI).

## E_FORBIDDEN_SCOPE

HTTP 403 · exit 7

You cannot publish to @….

**Fix:** Ask an owner of @… for publish rights, or use your own scope.

## E_GIT_MISSING

HTTP 500 · exit 8

Git is not installed or is older than 2.25.

**Fix:** Install Git 2.25 or later, then retry.

## E_NODE_VERSION

HTTP 500 · exit 8

GenPM needs Node.js 20.11 or later (found …).

**Fix:** Update Node.js, or install the standalone genpm binary, which does not need it: genpm.net/docs/install

## E_UPGRADE_UNSUPPORTED

HTTP 400 · exit 8

This copy of GenPM was installed with …: genpm upgrade only updates the standalone binary.

**Fix:** Update it with …, or install the binary from genpm.net/docs/install.

## E_UPGRADE_PERMISSION

HTTP 500 · exit 8

Cannot replace …: permission denied.

**Fix:** Run genpm upgrade as the user that owns that file, or reinstall with the script from genpm.net/docs/install.

## E_UPGRADE_INTEGRITY

HTTP 422 · exit 6

The downloaded … does not match its published SHA-256 checksum.

**Fix:** Nothing was changed. Retry later; if it happens again, report it to hello@genpm.net with the subject [SECURITY].

## E_MCP_SERVE_UNAVAILABLE

HTTP 500 · exit 8

genpm mcp serve is only built into the standalone genpm binary.

**Fix:** Use npx -y @genpm/mcp as the MCP command (genpm mcp setup does it for you), or install the binary from genpm.net/docs/install.

## E_NOT_A_PROJECT

HTTP 400 · exit 8

No project found in ….

**Fix:** Run the command inside a project (with package.json or .git), or pass --cwd <dir>.