Error codes
When FerrFlow encounters an error, it displays a code like error[E2001] with a link to this page. Use the code to find the cause and fix.
Configuration Errors
Section titled “Configuration Errors”E1001: Config file not found
Section titled “E1001: Config file not found”The config file specified via --config does not exist.
E1002: Failed to parse ferrflow.json
Section titled “E1002: Failed to parse ferrflow.json”The ferrflow.json file contains invalid JSON (missing commas, trailing commas, unquoted keys).
E1003: Failed to parse ferrflow.json5
Section titled “E1003: Failed to parse ferrflow.json5”The ferrflow.json5 file contains invalid JSON5.
E1004: Failed to parse ferrflow.toml
Section titled “E1004: Failed to parse ferrflow.toml”The ferrflow.toml file contains invalid TOML.
E1005: Failed to serialize to TOML
Section titled “E1005: Failed to serialize to TOML”Internal error when writing TOML output.
E1006: Failed to parse .ferrflow
Section titled “E1006: Failed to parse .ferrflow”The .ferrflow dotfile contains invalid JSON.
E1007: Failed to serialize .ferrflow
Section titled “E1007: Failed to serialize .ferrflow”Internal error when writing the dotfile.
E1008: Failed to resolve path
Section titled “E1008: Failed to resolve path”A path in the config could not be resolved to an absolute path.
E1009: Failed to write temporary loader file
Section titled “E1009: Failed to write temporary loader file”Could not write the temporary JS/TS loader during config evaluation.
E1010: Failed to execute tsx
Section titled “E1010: Failed to execute tsx”The tsx runtime could not be found or executed for .ts config files.
E1011: Failed to execute node
Section titled “E1011: Failed to execute node”The node runtime could not be found or executed for .js config files.
E1012: Config evaluation failed
Section titled “E1012: Config evaluation failed”The JS/TS config file threw an error during evaluation.
E1013: Invalid config output
Section titled “E1013: Invalid config output”The JS/TS config file produced non-UTF-8 output.
E1014: Invalid JSON from config
Section titled “E1014: Invalid JSON from config”The JS/TS config file did not produce valid JSON output.
E1015: Failed to read config file
Section titled “E1015: Failed to read config file”The config file exists but could not be read (permissions, encoding).
E1016: Multiple config files found
Section titled “E1016: Multiple config files found”More than one config file was found in the project root (e.g. both ferrflow.json and ferrflow.toml).
E1017: Config file already exists
Section titled “E1017: Config file already exists”Running ferrflow init when a config file already exists.
Validation Errors
Section titled “Validation Errors”E1100: Invalid repo spec
Section titled “E1100: Invalid repo spec”The --repo argument does not match the expected format owner/repo or host/owner/repo.
E1101: GitHub API error
Section titled “E1101: GitHub API error”The GitHub API returned an error during remote config validation.
E1102: GitLab API error
Section titled “E1102: GitLab API error”The GitLab API returned an error during remote config validation.
E1103: Invalid UTF-8 in config
Section titled “E1103: Invalid UTF-8 in config”The remote config file contains invalid UTF-8 encoding.
E1104: Failed to parse remote config
Section titled “E1104: Failed to parse remote config”The remote config file could not be parsed.
E1105: Remote config file not found
Section titled “E1105: Remote config file not found”The specified config file path does not exist in the remote repository.
E1106: No config file found
Section titled “E1106: No config file found”No FerrFlow config file was found in the remote repository.
E1107: —ref requires —repo
Section titled “E1107: —ref requires —repo”The --ref flag was used without specifying --repo.
Git Operation Errors
Section titled “Git Operation Errors”E2001: Not a git repository
Section titled “E2001: Not a git repository”The current directory is not inside a git repository.
E2002: Bare repository not supported
Section titled “E2002: Bare repository not supported”FerrFlow does not support bare git repositories.
E2003: Tag already exists
Section titled “E2003: Tag already exists”The tag that FerrFlow wants to create already exists.
E2004: Failed to push branch
Section titled “E2004: Failed to push branch”Could not push the release branch to the remote.
E2005: Push rejected by remote
Section titled “E2005: Push rejected by remote”The remote rejected the push (non-fast-forward, branch protection, hooks).
E2006: Failed to push tags
Section titled “E2006: Failed to push tags”Could not push tags to the remote.
E2007: Failed to push floating tags
Section titled “E2007: Failed to push floating tags”Could not force-push floating tags (e.g. v1, v1.2).
E2008: Remote not found
Section titled “E2008: Remote not found”The configured git remote (default: origin) does not exist.
E2009: Post-push verification failed
Section titled “E2009: Post-push verification failed”After pushing, the release commit could not be verified on the remote branch.
E2010: Remote branch not found
Section titled “E2010: Remote branch not found”The remote branch was not found after a push operation.
GitHub API Errors
Section titled “GitHub API Errors”E3001: Failed to create release
Section titled “E3001: Failed to create release”The GitHub Releases API returned an error when creating a release.
E3002: Failed to list releases
Section titled “E3002: Failed to list releases”Could not fetch existing releases from the GitHub API.
E3003: Failed to parse releases response
Section titled “E3003: Failed to parse releases response”The GitHub API returned an unexpected response format.
E3004: Failed to publish release
Section titled “E3004: Failed to publish release”Could not publish (un-draft) a GitHub release.
E3005: Failed to create pull request
Section titled “E3005: Failed to create pull request”The GitHub API returned an error when creating a PR.
E3006: Failed to parse PR response
Section titled “E3006: Failed to parse PR response”The GitHub API returned an unexpected PR response format.
E3007: PR response missing required field
Section titled “E3007: PR response missing required field”The GitHub API PR response was missing the number or node_id field.
E3008: Failed to enable auto-merge
Section titled “E3008: Failed to enable auto-merge”Could not enable auto-merge on the release PR via the GraphQL API.
E3009: Failed to parse GraphQL response
Section titled “E3009: Failed to parse GraphQL response”The GitHub GraphQL API returned an unexpected response.
E3010: Auto-merge failed
Section titled “E3010: Auto-merge failed”The GraphQL mutation to enable auto-merge returned an error.
GitLab API Errors
Section titled “GitLab API Errors”E3101: Failed to create release
Section titled “E3101: Failed to create release”The GitLab Releases API returned an error.
E3102: Failed to create merge request
Section titled “E3102: Failed to create merge request”The GitLab API returned an error when creating an MR.
E3103: Failed to parse MR response
Section titled “E3103: Failed to parse MR response”The GitLab API returned an unexpected MR response format.
E3104: MR response missing iid field
Section titled “E3104: MR response missing iid field”The GitLab MR response was missing the iid field.
E3105: Failed to merge MR
Section titled “E3105: Failed to merge MR”Could not merge the release MR via the GitLab API.
Version File Errors
Section titled “Version File Errors”TOML (E4101 to E4105)
Section titled “TOML (E4101 to E4105)”| Code | Error |
|---|---|
| E4101 | Cannot read TOML version file |
| E4102 | Invalid TOML syntax |
| E4103 | No version field found |
| E4104 | Failed to write TOML version file |
| E4105 | Invalid UTF-8 in TOML file |
JSON (E4201 to E4205)
Section titled “JSON (E4201 to E4205)”| Code | Error |
|---|---|
| E4201 | Cannot read JSON version file |
| E4202 | Invalid JSON syntax |
| E4203 | No version field found |
| E4204 | Failed to write JSON version file |
| E4205 | Invalid UTF-8 in JSON file |
Helm / YAML (E4301 to E4304)
Section titled “Helm / YAML (E4301 to E4304)”| Code | Error |
|---|---|
| E4301 | Cannot read Chart.yaml |
| E4302 | No version field found |
| E4303 | Failed to write Chart.yaml |
| E4304 | Invalid UTF-8 in Chart.yaml |
XML (E4401 to E4404)
Section titled “XML (E4401 to E4404)”| Code | Error |
|---|---|
| E4401 | Cannot read XML version file |
| E4402 | No <version> tag found |
| E4403 | Failed to write XML file |
| E4404 | Invalid UTF-8 in XML file |
CSProj (E4410 to E4413)
Section titled “CSProj (E4410 to E4413)”| Code | Error |
|---|---|
| E4410 | Cannot read .csproj file |
| E4411 | No <Version> tag found |
| E4412 | Failed to write .csproj file |
| E4413 | Invalid UTF-8 in .csproj file |
Gradle (E4501 to E4504)
Section titled “Gradle (E4501 to E4504)”| Code | Error |
|---|---|
| E4501 | Cannot read build.gradle |
| E4502 | No version field found |
| E4503 | Failed to write build.gradle |
| E4504 | Invalid UTF-8 in build.gradle |
Go mod (E4601 to E4603)
Section titled “Go mod (E4601 to E4603)”| Code | Error |
|---|---|
| E4601 | Failed to run git describe |
| E4602 | No version tag found — handled internally since v3 |
| E4603 | Go modules do not support write |
On E4602: starting with FerrFlow v3 the release flow catches this case and falls back to the strategy’s bootstrap baseline (0.0.0 / 0 / …), so the first release on a brand-new repo succeeds without a pre-seeded tag. The error code still exists for programs that import GoModVersionFile directly, but end users running ferrflow release should not see it anymore.
Text (E4701 to E4704)
Section titled “Text (E4701 to E4704)”| Code | Error |
|---|---|
| E4701 | Cannot read text version file |
| E4702 | No version found |
| E4703 | Failed to write text file |
| E4704 | Invalid UTF-8 in text file |
Pre-release Errors
Section titled “Pre-release Errors”E5001: Empty channel name
Section titled “E5001: Empty channel name”The pre-release channel name is empty.
E5002: Invalid channel name
Section titled “E5002: Invalid channel name”The channel name contains invalid characters. Only alphanumeric characters and hyphens are allowed.
Versioning Errors
Section titled “Versioning Errors”E5010: Invalid semver
Section titled “E5010: Invalid semver”The current version string is not valid semantic versioning.
Hook Errors
Section titled “Hook Errors”E6001: Hook execution failed
Section titled “E6001: Hook execution failed”A lifecycle hook exited with a non-zero status code and on_failure is set to abort.
Query Errors
Section titled “Query Errors”E7001: No packages configured
Section titled “E7001: No packages configured”No packages are defined in the config file.
E7002: Package not found
Section titled “E7002: Package not found”The specified package name does not exist in the config.
Monorepo Errors
Section titled “Monorepo Errors”E8001: Package not found in config
Section titled “E8001: Package not found in config”A package referenced during release was not found in the configuration.
E8002: Floating tag backward move
Section titled “E8002: Floating tag backward move”A floating tag would move to an older version.