Guide

Troubleshooting

Solutions to common errors and problems when using epack.

Signing Issues

"Browser did not open for signing"

Symptom:

$ epack sign evidence.pack
Opening browser for authentication...
# Hangs indefinitely

Cause: You're running in a headless environment (CI, SSH, Docker) without a browser.

Solution: In GitHub Actions, grant id-token: write and let epack use ambient OIDC automatically:

GitHub Actions
permissions:
  id-token: write

steps:
  - name: Sign pack
    run: epack sign evidence.pack

"OIDC token expired"

Symptom:

error: OIDC token has expired

Cause: OIDC tokens have short lifetimes (typically 5-15 minutes).

Solution: Request a fresh token immediately before signing. Don't cache tokens.

Verification Issues

"digest mismatch for artifacts/..."

Symptom:

error: digest mismatch for artifacts/config.json
  expected: sha256:a1b2c3d4e5f6...
  got:      sha256:7a8b9c0d1e2f...

Cause: The file was modified after the pack was created.

Solutions:

  • If you modified the file intentionally, rebuild the pack: epack build
  • If you didn't modify it, the pack may have been tampered with
  • Extract and compare: epack extract evidence.pack -o /tmp/extracted

"pack has no attestations"

Symptom:

error: pack has no attestations (required by --require-attestation)

Cause: The pack was never signed, but you're requiring a signature.

Solutions:

  • Sign the pack: epack sign evidence.pack
  • Or verify without requiring attestation: epack verify evidence.pack (without --require-attestation)

"identity mismatch"

Symptom:

error: identity mismatch
  expected subject: security@company.com
  got:              build-bot@company.com

Cause: The pack was signed by a different identity than you specified.

Solutions:

  • Check who actually signed: epack inspect evidence.pack
  • Update your --subject constraint to match the actual signer
  • Or have the correct identity re-sign the pack

Build Issues

"no artifacts to package"

Symptom:

error: no artifacts to package

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

Solutions:

  • Check your glob pattern: ls ./artifacts/*
  • Use quotes to prevent shell expansion: epack build out.pack "./artifacts/*"
  • Verify the files exist in the expected location

"file exceeds maximum size"

Symptom:

error: file exceeds maximum size (100MB): large-export.zip

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

Solutions:

  • Split large files into smaller chunks
  • Compress before adding: gzip large-export.json
  • Exclude the file and reference it externally

Collector Issues

"collector timed out"

Symptom:

error: collector 'github' timed out after 60s

Cause: The collector is taking too long to fetch data.

Solutions:

  • Increase timeout: epack collect --timeout 5m
  • Check network connectivity to the source
  • Verify API credentials are valid

"required secret not found"

Symptom:

error: required secret 'GITHUB_TOKEN' not found in environment

Cause: The collector requires a secret that's not set.

Solutions:

  • Set the environment variable: export GITHUB_TOKEN=ghp_xxx
  • Use a .env file and source it: source .env && epack collect
  • In a folder epack remote clone created, store it in your keychain: epack secret set GITHUB_TOKEN
  • In CI, add the secret to your workflow

"approval required" for a stored secret

Symptom:

Variables:   1 of 2 ready
  AZURE_CLIENT_SECRET    stored in your keychain; approval required
Findings:
  AZURE_CLIENT_SECRET: microsoft-cloud changed since you approved it
    (revision 3 to 4); run epack secret approve AZURE_CLIENT_SECRET

Cause: A newer revision of the configuration changed a component that reads the stored secret, or added one. The value is approved for the readers as they were when it was stored, and epack run stops before collecting until you approve the change. A run by name runs the newest earlier revision that works without the approval instead, when the remote has one.

Solutions:

  • Review the change and approve it: epack secret approve AZURE_CLIENT_SECRET
  • Or set the variable in the environment for this run, which bypasses the approval

"no session bus" or "the login keyring is locked"

Cause: On Linux the keychain is the Secret Service over D-Bus. A key-based SSH login or a host without a desktop has no unlocked keyring to read.

Solutions:

  • Run from a desktop session with gnome-keyring or kwallet, or unlock the login keyring
  • Set the variables in the environment instead; the keychain is read only for variables the environment lacks

Run Issues

"revision N needs ..., and no earlier revision runs here without it"

Cause: The revision epack run <name> fetched needs something this runner lacks: a variable or keychain secret, approval for a stored secret, a trusted publisher, or a newer epack. No earlier revision runs without it, so the run stopped before installing anything and reported what is missing to the remote.

Solutions:

  • Add each item the run listed, where the run says to add it, then run again
  • For a publisher, set EPACK_TRUSTED_PUBLISHERS or pass --trust-publisher
  • For a newer epack, upgrade to the release the run names

"the <remote> adapter comes from a publisher this run does not trust"

Cause: A job with no folder runs a configuration by name through the adapter installed for the user, and signs in for the configuration with it. The adapter must come from a publisher the job trusts, checked before it is installed or run.

Solutions:

  • Add the adapter's publisher, the GitHub owner of its source repository, to EPACK_TRUSTED_PUBLISHERS

Getting More Help

If your issue isn't listed here: