Faultline Failure Catalog

This index links to every bundled playbook. Each page explains the failure, shows the log signals Faultline matches, and lists diagnosis and fix steps.

182 playbooks across 9 categories.

Run faultline list to browse the catalog inside the terminal.

Auth (11)

• AWS credentials missing or invalid — The job could not authenticate with AWS.
• Docker registry authentication failure — CI could not authenticate to the container registry before an image pull or push.
• Expired credentials or rotated secrets — A CI job is using credentials that have expired, been revoked, or rotated outside of CI.
• Git authentication failure — The CI runner could not authenticate with the remote Git repository.
• HTTP request rejected with 401 or 403 status — An HTTP request was rejected with a 401 Unauthorized or 403 Forbidden status.
• Kubernetes cluster authentication failure — kubectl could not authenticate with the Kubernetes API server.
• Missing required environment variable — A required environment variable was not set in the CI environment.
• npm or yarn registry authentication failure — The Node.
• OIDC token request failed or token invalid — An OIDC token request failed or the issued token was rejected by the cloud provider.
• SSH key authentication failure — An SSH operation (git clone, deploy, rsync) failed because the SSH key was not found, not loaded into the agent, or the remote host does not accept it.
• SSH permission denied (publickey) authentication failed — SSH authentication to a Git host or remote server failed with explicit "Permission denied (publickey)" message.

Build (67)

• Alpine vs Debian/Ubuntu package or binary incompatibility — A CI build or container fails because it mixes Alpine Linux (musl libc) and Debian/Ubuntu (glibc) artifacts.
• Ansible YAML task or variable file syntax error — Ansible failed to parse a YAML file — a task file, variable file, role default, or handler — while loading the playbook.
• Docker base image update introduced a breaking change — A Docker build that previously succeeded now fails because the base image tag (e.
• Required build input file missing — A build or lint step referenced a file that was never generated, was copied to the wrong path, or is missing from the repository checkout.
• Build output artifact not found at expected path — A CI step that consumes the output of a prior build step cannot find the expected artifact at the configured path.
• Docker BuildKit session lost — Docker BuildKit lost its session while loading the build definition or context, so the image build stopped before it could execute any build steps.
• Corrupted or stale dependency cache — CI restored a dependency cache, but the cached contents were stale, corrupted, or built for an incompatible environment.
• Rust cargo build compilation failure — The Rust compiler rejected the crate with one or more hard errors — type mismatches, borrow checker violations, unresolved imports,
• CLI tool flag or command changed between versions — A CI script or Makefile invokes a CLI tool with a flag or subcommand that no longer exists in the installed version.
• Required configuration file not found — A required configuration file is absent from the CI workspace.
• Dependency version drift — Dependency constraints have drifted apart enough that the package manager cannot compute a valid install plan.
• Dependency removed or yanked from upstream registry — A required dependency has been removed, yanked, or unpublished from the upstream registry.
• Docker build context or Dockerfile path issue — Docker could not read the Dockerfile or a required file from the selected build context, so the image build stopped before executing the full build.
• Docker manifest not found or bad image tag — Docker could not pull an image because the tag does not exist in the registry, the manifest is missing, or the image reference is malformed.
• Docker COPY failed source file missing from build context — Docker COPY or ADD instruction failed because the source file does not exist in the build context.
• .NET NuGet package restore failure — dotnet restore or a build that implicitly runs restore could not download or resolve one or more NuGet packages.
• Unicode or character encoding error — A CI step failed because a file or data stream contains characters that cannot be interpreted in the assumed encoding.
• ESLint or linter check failure — A linting or formatting check step (eslint, tslint, prettier) found violations in the source code and exited with a non-zero
• ffmpeg or avconv not available in the CI environment — The job requires ffmpeg (or its libav counterpart avconv) for media processing but neither tool is installed or reachable on
• Docker base image uses a floating latest tag — A Dockerfile uses a :latest base image tag, so rebuilds can pull different bytes over time without a source change.
• Code formatting check failure — A CI formatting check failed because one or more source files do not match the project's required code style as
• Git refspec or branch does not exist — A git checkout or clone operation failed because the requested refspec (branch name, tag, or commit reference) does not exist on the remote repository.
• Go compilation error — The Go compiler rejected the package because of a semantic error — undefined identifier, type mismatch, unused import, or interface non-compliance.
• Missing go.sum entry — The build needs a module checksum that is missing from `go.
• Gradle build failure — Gradle exited with a non-zero status, indicating one or more tasks failed.
• Gradle daemon wrapper lock timeout — The Gradle or Maven daemon could not acquire an exclusive lock on cached wrapper files, causing the build tool initialization to timeout.
• Package installation failure — The dependency installation step failed because the requested package or version could not be found in the configured registry, package
• Configuration file fails schema validation — A configuration file exists but fails validation because a required field is missing, an unrecognized field is present, or a
• Line ending mismatch (CRLF vs LF) — A script or source file contains Windows-style CRLF line endings where Unix LF endings are expected.
• Maven Java compilation failure — The Maven compiler plugin failed during compilation.
• Maven or Gradle dependency resolution failure — The Java build could not resolve one or more dependencies or plugins from the configured artifact repositories.
• Unresolved merge conflict in source code — A file contains unresolved merge conflict markers (<<<<<<<, =======, >>>>>>>).
• Required executable or runtime binary missing — The job tried to launch a required tool or runtime binary, but that executable was missing from the image, runner, or expected path.
• MSBuild task or target failure — MSBuild exited with a fatal error MSBxxxx diagnostic.
• Multi-stage Docker build artifact not copied correctly — A multi-stage Docker build failed because a COPY --from=<builder> instruction references a file or directory that was not produced by
• node-gyp missing build tools — node-gyp failed because required build tools (Python, C++ compiler, etc.
• Node.js runtime or tool missing in CI — The CI job tried to run a Node.
• Node.js JavaScript heap out of memory — The Node.
• Node.js version mismatch — The Node.
• npm ci lockfile mismatch — npm ci found a missing or out-of-sync `package-lock.
• npm EACCES permission denied in node_modules — npm failed with an EACCES error while trying to write to node_modules or the global npm cache.
• npm ENOENT package.json missing — npm could not find a `package.
• npm ERESOLVE dependency tree conflict — npm encountered a dependency tree conflict that it could not automatically resolve.
• npm peer dependency conflict — npm could not build a valid dependency tree because one package requires a peer version that conflicts with what the project currently installs.
• Package manager mismatch in lockfile — CI used one package manager (e.
• File path case mismatch — A file or module import path uses a different capitalisation from the actual filename on disk.
• pip hash-checking mode failure — pip rejected one or more downloaded packages because their hash did not match the expected value recorded in `requirements.
• pip package install failure — pip install could not satisfy one or more package requirements.
• pnpm lockfile mismatch or frozen install failed — The pnpm lockfile (`pnpm-lock.
• pnpm frozen lockfile missing or mismatch — pnpm failed because the lockfile is missing, out of sync, or was not committed.
• Poetry lockfile drift — Poetry is installing from a lockfile that no longer matches `pyproject.
• Python or pip command not found — The python or pip command is not available in the CI environment's PATH.
• Python externally managed environment error — pip refused to install packages because Python 3.
• Python module not found — Python could not import a required module because it is missing from the environment used by the failing CI step
• Python virtualenv not activated or interpreter mismatch — Python code is using a system interpreter or wrong virtualenv instead of the activated one, causing module import failures or version mismatches.
• Lint, format, or static-analysis gate failure — A non-compiler quality gate failed during CI.
• Python, Ruby, or Go runtime version mismatch — The installed Python, Ruby, or Go runtime does not satisfy the version constraint declared by the project.
• Bash syntax used under a POSIX sh shell — A CI workflow or script selects sh but uses Bash-only syntax such as `[[ .
• Shell compatibility issue (sh vs bash) — A shell script uses bash-specific syntax but is executed by /bin/sh, which is commonly dash on Ubuntu/Debian or ash on Alpine.
• Symlink resolution failure in CI — A symlink in the repository or the build workspace is broken or cannot be resolved in the CI environment.
• Syntax error in source code — The compiler or interpreter hit invalid source syntax and stopped before the build could continue.
• Cross-ownership boundary failure — A change in one ownership zone has broken code in a separate ownership zone, suggesting the failure originates at a
• tox environment command failed (InvocationError) — tox ran a command inside a virtual environment and the command exited with a non-zero status.
• TypeScript compile or type-check failure — The TypeScript compiler rejected the code because a type, symbol, or module import does not match the project's declared types.
• Wrong working directory — A command ran in an unexpected working directory.
• Monorepo workspace dependency version mismatch — A package in the monorepo workspace depends on a version of another workspace package that doesn't match the version published
• Yarn lockfile out of date — Yarn was run with --frozen-lockfile (the recommended CI flag) but the `yarn.

Ci (26)

• CI artifact upload or download failed — A CI job failed to upload a build artifact, or a downstream job failed to download an artifact produced by an earlier job.
• Azure Pipelines service connection failure — An Azure Pipelines job failed because the service connection required by a task does not exist, is not authorized, or has expired credentials.
• Azure Pipelines task version not found or deprecated — An Azure Pipelines job could not start because a pipeline task references a version that has been deprecated, removed, or
• CircleCI config.yml validation error — CircleCI rejected the `.
• CircleCI machine image or resource class not valid — A CircleCI job failed to start because the specified machine image or resource class is no longer valid, was removed,
• CircleCI job killed — resource class memory limit exceeded — The CircleCI job was killed because it exceeded the memory limit of the selected resource class.
• Git shallow clone missing history or tags — The CI job performed a shallow Git clone and a later step requires full commit history or tags.
• Git submodule not initialized or updated — A Git submodule referenced by the repository has not been initialized or updated.
• GitHub Actions job cancelled by concurrency policy — A GitHub Actions workflow run was automatically cancelled because a newer run for the same concurrency group started.
• GitHub Actions environment variable not persisted across steps — A GitHub Actions step exported an environment variable using the deprecated ::set-env workflow command, which is now disabled.
• GitHub Actions matrix axis variable undefined — A GitHub Actions workflow uses an undefined matrix axis variable in a step or action, causing the workflow to fail during variable resolution.
• GitHub Actions missing actions/checkout before accessing repo files — GitHub Actions job tried to access repository files (build, test, run scripts) but the repository was never checked out.
• GitHub Actions GITHUB_TOKEN permission denied — The GITHUB_TOKEN used by this workflow does not have the permissions required for the requested GitHub operation.
• GitHub Actions runner capacity or queue timeout — The GitHub Actions job waited too long to be picked up by a runner, or the runner became unresponsive mid-job.
• GitHub Actions workflow validation or action reference error — GitHub Actions rejected the workflow definition or could not resolve a referenced action, so the workflow could not validate cleanly
• GitLab CI artifact missing or expired — A downstream GitLab CI job could not retrieve an artifact produced by an earlier job because it expired, was never
• GitLab CI pipeline configuration invalid — The `.
• GitLab CI job log size limit exceeded — The GitLab CI job produced more output than the runner's configured log size limit.
• GitLab CI job stuck — no matching runner — GitLab CI could not find an available runner that matches the job's tag requirements or the project has no registered runners at all.
• Jenkins build agent went offline during job — The Jenkins build agent disconnected or went offline while running a job.
• Jenkins required plugin missing or incompatible — A Jenkins job or pipeline step failed because a required plugin is not installed, is disabled, or has an incompatible version.
• Orphaned CI resources blocking subsequent runs — A CI job failed because a previous run left behind a container, network, volume, or bound port that was not cleaned up.
• CI job or pipeline exceeded time limit — The CI job ran past its configured time limit and was killed by the CI system.
• CI runner disk full — The CI runner has run out of available disk space.
• Self-hosted runner update permission failure — A self-hosted runner tried to update itself or adjust worker process settings, but the environment denied access to the runner
• CI secret or environment variable not available — A required secret or environment variable is not available in this CI job.

Deploy (11)

• Deployment configuration mismatch — The deployment failed because a required configuration value, environment variable, or secret was absent or had an unexpected value for
• Container exited unexpectedly — The container started but then exited with a non-zero status code.
• Service health check failure — The new service instance never became healthy enough for traffic.
• Container image pull failure — The deployment failed because the runtime could not pull the requested container image from the registry.
• Kubernetes pod in CrashLoopBackOff — A Kubernetes pod is stuck in CrashLoopBackOff: the container starts, exits with a non-zero code, and Kubernetes restarts it with exponential back-off.
• MySQL connection refused or service unavailable — The application or test suite could not connect to MySQL.
• Port already in use during deployment — A container or service failed to start because the port it needs to bind to is already occupied by another
• PostgreSQL connection refused or service unavailable — The application could not connect to PostgreSQL.
• Redis connection refused or service unavailable — The application or test suite could not connect to Redis.
• Terraform initialization failure — terraform init failed before any plan or apply could begin.
• Terraform state lock conflict — Terraform could not acquire the state lock because another Terraform process is currently holding it.

Network (11)

• Service or dependency connection refused — A TCP connection attempt was actively refused by the target host.
• DNS resolution failed ENOTFOUND — DNS resolution failed for a hostname.
• DNS resolution failure — The runner could not resolve a hostname to an IP address, so the network call failed before it could connect.
• Outbound network traffic blocked by firewall or security group — An outbound network connection was blocked before reaching its destination.
• IPv6 vs IPv4 DNS resolution failure in CI container — CI container or test environment fails to connect because the system resolves a hostname to an IPv6 address (AAAA record)
• LDAP server unreachable — The LDAP client could not reach the directory server.
• Network request timeout — A network request exceeded its timeout limit.
• Corporate or CI proxy misconfiguration blocking outbound traffic — Outbound HTTP(S) traffic from CI fails because the runner is behind a corporate proxy that is not configured in the
• Request rate-limited by external service — A request to an external service was rejected with HTTP 429 Too Many Requests or an equivalent rate-limit error.
• Package registry or CDN outage — The dependency installation step failed because the upstream package registry (npm, PyPI, Maven Central, RubyGems, etc.
• SSL/TLS certificate error — A TLS/SSL certificate error prevented a secure connection.

Runtime (20)

• CPU architecture or platform mismatch — A binary, container image, or build artifact targets the wrong CPU architecture for the current runner.
• Disk space exhausted — The host or container filesystem ran out of disk space.
• Docker daemon configuration conflict prevents startup — The Docker daemon failed to start because conflicting options were supplied — the same setting was configured both in `daemon.
• Docker daemon unavailable — Docker could not reach the daemon socket or service, so the step failed before it could inspect containers or run a build.
• Docker permission denied running as non-root user — A Docker container process running as a non-root user encountered a permission denied error while trying to access files or
• Docker entrypoint or CMD misconfiguration — A Docker container exits immediately after start because its ENTRYPOINT or CMD is misconfigured.
• Required environment variable missing or empty — A required environment variable was not set or was empty when the process tried to read it.
• Goroutine spawned without context or stop channel — A goroutine is spawned with an infinite loop and no context cancellation, stop channel, or WaitGroup — it will leak
• HTTP client used without a timeout — An HTTP request is made using the package-level `http.
• Error return value ignored or silently discarded — An error return from an I/O, database, or side-effecting call is discarded with _ = or silently overwritten, so failures pass undetected.
• Database transaction opened without a deferred rollback — A database transaction is opened and committed in the same function with no `defer tx.
• Process killed by OOM killer — The process was terminated by the operating system's out-of-memory (OOM) killer.
• Unrecovered panic in HTTP or RPC handler — A panic call appears inside an HTTP or RPC handler with no recover() in a deferred function, which can crash
• Permission denied — The process tried to read, write, execute, or connect to a resource it does not have permission to access.
• Port already in use — A process attempted to bind to a TCP or UDP port that is already occupied by another process on the same CI runner.
• Process killed without diagnostic output — A CI process was killed externally, producing little or no diagnostic output.
• Resource limit exceeded — The process exceeded an OS-enforced resource limit such as the maximum number of threads or processes.
• Process terminated by segmentation fault or fatal signal — The process received a fatal signal — most commonly SIGSEGV (segmentation fault), SIGABRT (assertion failure), or SIGBUS (bus error) —
• Unawaited promise in async JavaScript or TypeScript code — An async JavaScript or TypeScript function starts a promise-returning operation but never awaits or catches it.
• Docker volume mount failure or inaccessible mount — A Docker container failed to start or operate correctly because a volume or bind mount is inaccessible.

Security (1)

• TLS certificate verification disabled in HTTP client — TLS certificate verification is explicitly disabled, allowing the client to connect to servers with invalid, expired, or self-signed certificates without

Silent Failure (11)

• Artifact upload step ran but no files were found — An artifact upload step was executed but reported that no files matched the configured path.
• Cache restore or save failed but job continued — A cache restore or save step failed (cache not found, restore error, or save error), but the CI job continued without flagging this as a failure.
• CI step configured to continue on error — A CI step uses continue-on-error: true or allow_failure: true, which causes the pipeline to proceed even when the step exits non-zero.
• Critical CI step allowed to fail — A CI workflow marks a critical build, test, deploy, artifact, or security step with continue-on-error: true, so the workflow can
• Deploy or publish step ran but had nothing deployable — A deploy, apply, publish, or release step ran, but the log indicates there was nothing deployable to apply or publish.
• Lint, scan, or coverage step ran but checked nothing — A lint, security-scan, or coverage step ran, but the log shows it processed zero files or produced no meaningful report.
• Hardcoded secret, token, or password in source code — A secret-named variable is assigned a literal string value in source code, exposing credentials, API keys, or tokens to anyone with repository access.
• Command failure suppressed with exit-code override — A failing command's exit code was deliberately suppressed using || true, set +e, or similar shell constructs.
• CI command failure hidden by shell exit-code swallowing — A CI script or workflow swallows a critical shell command failure with || true or set +e, allowing the job to pass after important work failed.
• Critical CI step skipped due to condition — A CI step was skipped because its if: condition evaluated to false.
• Test command ran but zero tests were executed — A test runner command was invoked but discovered or executed zero tests.

Test (24)

• Cargo test suite reported one or more test failures — One or more Rust tests failed.
• Generic coverage gate failure — The test step completed, but the job failed because measured coverage fell below an enforced minimum.
• Cucumber/Gherkin scenario step failed — One or more Cucumber scenarios failed.
• Database migration timeout or lock contention — Database migration failed to complete within the timeout window, usually due to lock contention or expensive DDL operations during test
• Test database state pollution between tests — Tests are polluting a shared database with committed data that later tests did not expect to find.
• Flaky test failure — A test failed but the failure is not consistently reproducible.
• Go race detector found a data race — The Go race detector identified a data race: two goroutines accessed the same memory location concurrently, with at least one
• Go test suite reported one or more test failures — One or more Go test functions failed or panicked.
• jest command not found or not installed — The jest command could not be found.
• Jest test suite reported one or more test failures — One or more Jest tests failed.
• Jest worker process crashed unexpectedly — A Jest worker process crashed mid-test run.
• JUnit / SBT test suite reported one or more test failures — One or more JVM test cases failed.
• Missing test fixture or seed data — A test failed because it could not load a required fixture file, seed record, or test helper resource that was expected to exist before the test ran.
• Test order dependency — A test failed because it depends on side effects or state created by a different test that ran earlier.
• Test parallelism conflict — Parallel test execution caused a resource conflict: two tests tried to bind the same port, access the same fixture, or
• PostgreSQL ALTER TYPE ADD VALUE cannot run inside a transaction block — A database migration that adds a value to a PostgreSQL ENUM type fails because PostgreSQL does not permit ALTER TYPE .
• PostgreSQL migration failed due to unsupported type or constraint syntax — A database migration failed because the PostgreSQL version in CI does not support a type or constraint syntax used in the migration (e.
• pytest fixture setup or teardown failure — A pytest fixture failed during setup or teardown, causing the associated test to be marked as ERROR rather than FAILED.
• pytest collected zero tests — pytest exited with code 5 because it collected zero tests.
• Snapshot or golden-file mismatch — A test compared current output against a committed snapshot or golden file and found a difference.
• Test assertion failure with explicit reason message — A test case assertion failed with an explicit reason message.
• Test suite or individual test timed out — A test (or the entire test suite) did not complete within the configured timeout period.
• Testcontainers container failed to start — A test using Testcontainers could not start the required Docker container.
• Timezone differences causing test failures — A test that compares date or time values fails because the CI runner operates in a different timezone than the development machine.

---

Generated from playbooks/bundled/. Do not edit directly — run make docs-generate.