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: Use an OIDC token instead of interactive browser auth:

GitHub Actions
permissions:
  id-token: write

steps:
  - name: Sign pack
    run: epack sign evidence.pack
    env:
      EPACK_OIDC_TOKEN: ${{ steps.id_token.outputs.token }}

"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 CI, add the secret to your workflow

Getting More Help

If your issue isn't listed here: