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

E1001: Config file not found

The config file specified via --config does not exist.

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

The ferrflow.json5 file contains invalid JSON5.

E1004: Failed to parse ferrflow.toml

The ferrflow.toml file contains invalid TOML.

E1005: Failed to serialize to TOML

Internal error when writing TOML output.

E1006: Failed to parse .ferrflow

The .ferrflow dotfile contains invalid JSON.

E1007: Failed to serialize .ferrflow

Internal error when writing the dotfile.

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

Could not write the temporary JS/TS loader during config evaluation.

E1010: Failed to execute tsx

The tsx runtime could not be found or executed for .ts config files.

E1011: Failed to execute node

The node runtime could not be found or executed for .js config files.

E1012: Config evaluation failed

The JS/TS config file threw an error during evaluation.

E1013: Invalid config output

The JS/TS config file produced non-UTF-8 output.

E1014: Invalid JSON from config

The JS/TS config file did not produce valid JSON output.

E1015: Failed to read config file

The config file exists but could not be read (permissions, encoding).

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

Running ferrflow init when a config file already exists.

Validation Errors

E1100: Invalid repo spec

The --repo argument does not match the expected format owner/repo or host/owner/repo.

E1101: GitHub API error

The GitHub API returned an error during remote config validation.

E1102: GitLab API error

The GitLab API returned an error during remote config validation.

E1103: Invalid UTF-8 in config

The remote config file contains invalid UTF-8 encoding.

E1104: Failed to parse remote config

The remote config file could not be parsed.

E1105: Remote config file not found

The specified config file path does not exist in the remote repository.

E1106: No config file found

No FerrFlow config file was found in the remote repository.

E1107: --ref requires --repo

The --ref flag was used without specifying --repo.

Git Operation Errors

E2001: Not a git repository

The current directory is not inside a git repository.

E2002: Bare repository not supported

FerrFlow does not support bare git repositories.

E2003: Tag already exists

The tag that FerrFlow wants to create already exists.

E2004: Failed to push branch

Could not push the release branch to the remote.

E2005: Push rejected by remote

The remote rejected the push (non-fast-forward, branch protection, hooks).

E2006: Failed to push tags

Could not push tags to the remote.

E2007: Failed to push floating tags

Could not force-push floating tags (e.g. v1, v1.2).

E2008: Remote not found

The configured git remote (default: origin) does not exist.

E2009: Post-push verification failed

After pushing, the release commit could not be verified on the remote branch.

E2010: Remote branch not found

The remote branch was not found after a push operation.

GitHub API Errors

E3001: Failed to create release

The GitHub Releases API returned an error when creating a release.

E3002: Failed to list releases

Could not fetch existing releases from the GitHub API.

E3003: Failed to parse releases response

The GitHub API returned an unexpected response format.

E3004: Failed to publish release

Could not publish (un-draft) a GitHub release.

E3005: Failed to create pull request

The GitHub API returned an error when creating a PR.

E3006: Failed to parse PR response

The GitHub API returned an unexpected PR response format.

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

Could not enable auto-merge on the release PR via the GraphQL API.

E3009: Failed to parse GraphQL response

The GitHub GraphQL API returned an unexpected response.

E3010: Auto-merge failed

The GraphQL mutation to enable auto-merge returned an error.

GitLab API Errors

E3101: Failed to create release

The GitLab Releases API returned an error.

E3102: Failed to create merge request

The GitLab API returned an error when creating an MR.

E3103: Failed to parse MR response

The GitLab API returned an unexpected MR response format.

E3104: MR response missing iid field

The GitLab MR response was missing the iid field.

E3105: Failed to merge MR

Could not merge the release MR via the GitLab API.

Version File Errors

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)

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)

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)

Code	Error
E4401	Cannot read XML version file
E4402	No tag found
E4403	Failed to write XML file
E4404	Invalid UTF-8 in XML file

CSProj (E4410 to E4413)

Code	Error
E4410	Cannot read .csproj file
E4411	No tag found
E4412	Failed to write .csproj file
E4413	Invalid UTF-8 in .csproj file

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)

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)

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

E5001: Empty channel name

The pre-release channel name is empty.

E5002: Invalid channel name

The channel name contains invalid characters. Only alphanumeric characters and hyphens are allowed.

Versioning Errors

E5010: Invalid semver

The current version string is not valid semantic versioning.

Hook Errors

E6001: Hook execution failed

A lifecycle hook exited with a non-zero status code and on_failure is set to abort.