Error Codes - epack

Programmatic access: Use errors.CodeOf(err) in Go to extract the error code from wrapped errors.

Integrity Errors

E001 DIGEST_MISMATCH

errors.DigestMismatch

CLI Message: digest mismatch for <path>

Cause: The file's content doesn't match the digest recorded in the manifest.

Resolution: Either rebuild the pack with the current files, or restore the original file content.

E002 MANIFEST_INVALID

errors.ManifestInvalid

CLI Message: invalid manifest: <details>

Cause: The manifest.json is malformed or doesn't conform to the schema.

Resolution: Check the manifest JSON syntax. Rebuild the pack if corrupted.

E003 ARTIFACT_MISSING

errors.ArtifactMissing

CLI Message: artifact not found: <path>

Cause: The manifest references a file that doesn't exist in the pack.

Resolution: The pack may be corrupted. Obtain a fresh copy.

E004 PACK_CORRUPT

errors.PackCorrupt

CLI Message: pack is corrupt or not a valid ZIP

Cause: The .epack file is not a valid ZIP archive.

Resolution: The file was corrupted during transfer. Re-download or rebuild.

Signature Errors

E010 SIGNATURE_INVALID

errors.SignatureInvalid

CLI Message: signature verification failed

Cause: The cryptographic signature doesn't validate against the manifest.

Resolution: The pack may have been modified after signing. Obtain a fresh signed copy.

E011 IDENTITY_MISMATCH

errors.IdentityMismatch

CLI Message: identity mismatch: expected <subject>, got <actual>

Cause: The signer identity doesn't match your --subject or --issuer constraint.

Resolution: Check who signed the pack with epack inspect. Update your constraints or have the correct identity re-sign.

E012 NO_ATTESTATION

errors.NoAttestation

CLI Message: pack has no attestations

Cause: --require-attestation was specified but the pack is unsigned.

Resolution: Sign the pack with epack sign, or remove the --require-attestation flag.

E013 ATTESTATION_EXPIRED

errors.AttestationExpired

CLI Message: attestation certificate has expired

Cause: The Sigstore certificate used to sign the pack has expired and the timestamp is outside the validity window.

Resolution: Re-sign the pack with a fresh certificate.

Build Errors

E020 NO_ARTIFACTS

errors.NoArtifacts

CLI Message: no artifacts to package

Cause: The glob pattern didn't match any files.

Resolution: Check your file paths and glob patterns. Use quotes to prevent shell expansion.

E021 FILE_TOO_LARGE

errors.FileTooLarge

CLI Message: file exceeds maximum size: <path>

Cause: Individual files are limited to 100MB by default.

Resolution: Compress large files, split them, or use --max-file-size to increase the limit.

E022 STREAM_INVALID

errors.StreamInvalid

CLI Message: invalid stream identifier: <stream>

Cause: The stream name doesn't match the required format.

Resolution: Use format org/name or org/name/env. Alphanumeric, hyphens, and slashes only.

Collector Errors (Full Edition)

E030 COLLECTOR_TIMEOUT

errors.CollectorTimeout

CLI Message: collector '<name>' timed out after <duration>

Cause: The collector didn't complete within the timeout period.

Resolution: Increase timeout with --timeout, check network connectivity, verify API credentials.

E031 SECRET_MISSING

errors.SecretMissing

CLI Message: required secret '<name>' not found in environment

Cause: A required environment variable is not set.

Resolution: Set the environment variable before running epack (for example: source .env && epack collect).

E032 LOCKFILE_MISMATCH

errors.LockfileMismatch

CLI Message: lockfile mismatch: run 'epack lock' to update

Cause: --frozen was specified but the lockfile doesn't match dependencies.

Resolution: Run epack lock locally and commit the updated lockfile.

E033 LOCK_CONFIG_MISMATCH

errors.LockConfigMismatch

CLI Message: locked version <version> for <kind> '<name>' does not satisfy configured constraint '<range>'

Cause: epack.yaml and epack.lock.yaml no longer describe the same components: a component is declared but not locked, locked with a different kind or source, or pinned to a version outside its configured range (for example after a range bump without re-locking).

Resolution: Run epack lock (or epack collector lock) to re-resolve within the configured range, then commit the updated lockfile. In --locked or --frozen CI runs this fails loudly instead of silently keeping the old pin.

E034 LOCK_STALE

errors.LockStale

CLI Message: lockfile has <kind> '<name>' not found in config

Cause: The lockfile pins a source-based component that no longer exists in epack.yaml, usually after a component was removed from config without re-locking.

Resolution: Run epack lock to drop the stale entry, or add the component back to config.

E035 LOCK_MISSING_PINNED_ARTIFACT

errors.LockMissingPinnedArtifact

CLI Message: <kind> '<name>' has no entry for platform <os/arch>

Cause: The lockfile pins the component but is missing the current platform's entry, a required digest, or an installable binary, so strict modes cannot verify what would run.

Resolution: Run epack lock --platform <os/arch> to pin the platform and compute digests, then commit the updated lockfile. Exits with code 14 (missing binary).

Exit Codes

Exit codes are divided into general codes (0-9) and component-specific codes (10-19).

General Exit Codes

Code	Meaning
`0`	Success
`1`	General error (invalid input, runtime error, etc.)
`2`	Malformed pack (pack cannot be opened or parsed)

Component Exit Codes (10-19)

Code	Meaning
`10`	Lock invalid (lockfile missing, invalid, or mismatched)
`11`	Digest mismatch (binary/artifact digest doesn't match expected)
`12`	Signature mismatch (Sigstore signature verification failed)
`13`	Timeout (operation timed out)
`14`	Missing binary (required binary not found/installed)
`15`	Network error (network error during fetch)

Machine-Readable Error Output

Set the EPACK_ERROR_FILE environment variable to a file path and every failed epack command appends three machine-readable lines to it, in the same append style as GitHub's $GITHUB_OUTPUT:

code=lock_config_mismatch
exit=10
summary=locked version v0.2.9 for collector "github" does not satisfy configured constraint "^0.3.0"

code is the stable error code, exit is the process exit code, and summary is the first line of the sanitized error message (secrets are redacted before writing). CI workflows use this to branch on stable codes without scraping logs, for example to pass --failure-code to epack remote report-lock or to render a job summary:

export EPACK_ERROR_FILE="$RUNNER_TEMP/epack-error.txt"
if ! epack sync --locked; then
  source "$EPACK_ERROR_FILE"
  epack remote report-lock locktivity --reason frozen_check \
    --outcome failure --failure-code "$code" --failure-message "$summary"
  exit "$exit"
fi