Skip to main content

🛠️ Troubleshooting Common Agent Failures

This page consolidates all recurring issues across Early AI agents — including the GitHub PR Action, CLI PR, Commit CLI, and Repository CLI.
Each section below addresses a common failure type, its symptoms, root causes, and how to fix it.

Use this as your single reference for debugging any Early AI workflow.

❌ API Key Missing or Invalid​

Symptoms​

  • Error: Missing required environment variable: API_KEY
  • CLI exits immediately after initialization
  • Logs show: 401 Unauthorized when contacting Early backend

Cause​

The agent cannot authenticate with the Early backend.

Fix​

  1. Ensure API_KEY is defined in your CI/CD environment (EARLY_API_KEY or equivalent).
  2. Confirm it matches the key issued to your organization.
  3. In GitHub Actions: 
    env:
      API_KEY: ${{ secrets.EARLY_API_KEY }}
  4. Contact support@startearly.ai if your key is expired or unknown.

❌ GitHub or SCM Token Missing or Insufficient​

Symptoms​

  • fatal: Authentication failed for 'https://github.com/org/repo.git/'
  • 401 Unauthorized: Unable to access package or commit
  • Error: Permission denied while committing files

Cause​

The token used for source control (GitHub, Bitbucket, etc.) lacks sufficient permissions.

Fix​

  1. Set the TOKEN environment variable to a valid Personal Access Token (PAT) or App Password.
  2. Review token scopes in Source Control Tokens →.
  3. For GitHub:
    • Classic PAT → repo, read:packages
    • Fine-grained PAT → Contents: Read & Write, Pull Requests: Read & Write, Metadata: Read
  4. For Bitbucket:
    • App Password → Repositories: Read & Write
  5. For GitLab:
    • Personal Access Token → api, read_repository, write_repository

If you still see permission issues, verify the token is scoped to the correct repository.

❌ NPM Authentication Fails (Cannot Install CLI)​

Symptoms​

  • npm ERR! 401 Unauthorized
  • Unable to authenticate, need: Bearer token

Cause​

The CLI is installed from GitHub Packages, which requires a classic token with read:packages.

Fix​

  1. Set up .npmrc correctly in your pipeline: 
    echo "@earlyai:registry=https://npm.pkg.github.com" >> ~/.npmrc
    echo "//npm.pkg.github.com/:_authToken=${NPM_TOKEN}" >> ~/.npmrc
  2. Ensure NPM_TOKEN is a classic PAT with read:packages.
  3. Fine-grained tokens and ${{ secrets.GITHUB_TOKEN }} will not work.

See NPM Authentication →.

❌ Out of Memory (Node.js Heap Limit)​

Symptoms​

  • FATAL ERROR: Ineffective mark-compacts near heap limit
  • Allocation failed - JavaScript heap out of memory

Cause​

Node.js exceeded its memory limit during test generation — usually when MAX_CONCURRENCY=4.

Fix​

Option 1 — Reduce concurrency:

export MAX_CONCURRENCY=3

Option 2 — Increase Node.js memory:

export NODE_OPTIONS="--max-old-space-size=5120"

Do not exceed 6000 MB on standard GitHub runners.
See Memory Tuning → for more guidance.

❌ Linting or Formatting Fails​

Symptoms​

  • Commit step fails even though tests were generated successfully
  • ESLint or Prettier errors appear in logs
  • pre-commit hook failed

Cause​

Your repository enforces linting or formatting rules, and Early-generated tests don’t meet them.

Fix​

Define these environment variables in your CI configuration:

export LINT_COMMAND="npx --no eslint $early_filename --fix"
export PRETTIER_COMMAND="npx --no prettier $early_filename --write"

These commands ensure generated test files are fixed and formatted before commit.
See Lint & Formatting.

❌ Test or Coverage Command Fails​

Symptoms​

  • jest: command not found
  • Coverage directory missing
  • Test suite failed to run

Cause​

Coverage or test commands in the project are misconfigured or missing dependencies.

Fix​

  1. Verify Jest is installed: 
    npm install --save-dev jest
  2. Ensure your project can run npx jest successfully.
  3. If needed, override commands in your configuration: 
    export TEST_COMMAND="npm run test"
    export COVERAGE_COMMAND="npm run coverage"
  4. See Concurrency & Performance for runtime tuning.

❌ Nothing Generated / No Tests Created​

Symptoms​

  • CLI runs successfully but no test files appear
  • Logs show “0 files processed”

Cause​

All target functions already have coverage above the current threshold (0% detection for now).

Fix​

  • Ensure the folder or commit includes untested code.
  • For folder-based runs, target directories like src/utils or lib/legacy.
  • Upcoming versions will include adjustable thresholds.

❌ Git Push or Commit Rejected​

Symptoms​

  • error: failed to push some refs
  • rejected: fetch first

Cause​

The branch changed while Early was generating tests, or Git identity was not configured.

Fix​

  1. Ensure GIT_USER_EMAIL and GIT_USER_NAME are set: 
    export GIT_USER_EMAIL="ci@earlyai.com"
    export GIT_USER_NAME="Early Bot"
  2. In GitHub Actions, add: 
    - uses: actions/checkout@v4
      with:
        fetch-depth: 0
  3. Re-run the workflow once the branch is up to date.

❌ Repository or SCM Connection Issues​

Symptoms​

  • fatal: not a git repository
  • Error: cannot find remote origin

Cause​

The CI job lacks Git setup or correct SCM configuration.

Fix​

  • Verify SCM_PROVIDER is defined (github, bitbucket, or gitlab).
  • Ensure your build agent includes Git.
  • For Jenkins and CircleCI, use full checkouts instead of shallow clones.
  • Review SCM Support →.

💬 Still Stuck?​

If problems persist:

  • Email support@startearly.ai with your logs and agent name.
  • Mention your CI/CD system (e.g., Jenkins, GitHub Actions, CircleCI).

👉 Next: FAQ