Skip to main content
Solutions for common build failures, answers to frequently asked questions, and a guide for migrating from legacy interactive setup.
For general environment configuration, see Environment Configuration. For syntax details, see the YAML Reference.

​
Debugging build failures

​
Step 1: Check the build status

Navigate to Settings > Devin’s Environment > Build History. Your build will show one of these statuses:
StatusWhat it meansWhat to do
SuccessEverything workedNothing — your machine image is ready
PartialCore build succeeded but some repos failedCheck which repos failed; their sessions may have issues
FailedThe build itself failedCheck logs for the failing step
CancelledA newer build superseded this oneNormal — start a newer build if needed
SkippedNo configuration changes detectedNothing — no build was needed

​
Step 2: Read the build logs

Build logs are organized by step:
  1. Shared setup — enterprise + org-wide commands
  2. Clone — repository cloning
  3. Repo setup — per-repository commands
  4. Finalize — health check and image creation
Look for the first error in the logs. Subsequent errors are often cascading failures caused by the first one.
If you used the expanded form with name fields, the logs will show exactly which step failed. This is one of the biggest benefits of naming your steps: 
# Without names — hard to debug
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  npm install -g pnpm

# With names — easy to spot failures
initialize:
  - name: Install uv
    run: curl -LsSf https://astral.sh/uv/install.sh | sh
  - name: Install pnpm
    run: npm install -g pnpm

​
Step 3: Identify the failure pattern

​
Clone failures

Symptom: Build fails during cloning. Common causes:
  • Repository access not configured — check Enterprise Settings > Integrations
  • Private repo requires an authentication token
  • Repository was renamed or deleted
  • Network connectivity issue (VPN or proxy needed)
Fix: Verify Devin has access to the repository in your integration settings. For private registries, ensure credentials are configured in Secrets.

​
Dependency install failures

Symptom: Build fails during repo setup, usually on npm install, pip install, or similar. Common causes:
  • Private package registry requires authentication — add token to Secrets
  • Package version conflict — pin specific versions
  • Network timeout — check if VPN is needed
  • Registry URL misconfigured
Fix: Add registry authentication in your maintenance section. See Configuration Examples for private registry patterns.

​
Timeout failures

Symptom: Build appears stuck, then fails. Common causes:
  • Interactive prompt waiting for input — add -y flags, use DEBIAN_FRONTEND=noninteractive
  • Very large dependency installation taking too long
  • Command exceeds the 1-hour timeout
Fix: Add non-interactive flags to all install commands. Move slow one-time installations to initialize so they only run during builds (not every session). 
# Bad — will hang waiting for input
initialize: |
  sudo apt-get install libpq-dev

# Good — non-interactive
initialize: |
  sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev

​
Permission errors

Symptom: “Permission denied” in logs. Common causes:
  • Missing sudo for system package installation
  • Trying to write to protected directories
  • File owned by a different user from a previous build
Fix: Use sudo for system-level operations (apt-get, writing to /etc/, etc.). For user-level package managers (npm, pip, cargo), sudo is usually not needed.

​
”Command not found” errors

Symptom: A tool installed in initialize isn’t available in maintenance or later steps. Common causes:
  • Tool installs to a directory not on PATH
  • Shell profile (.bashrc) changes not sourced in subsequent steps
Fix: Add the tool’s directory to PATH via $ENVRC: 
initialize: |
  curl -LsSf https://astral.sh/uv/install.sh | sh
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC

​
Step 4: Iterate

After identifying the issue:
  1. Fix your YAML configuration
  2. Save — a new build starts automatically
  3. Check the new build’s logs
Test commands first. Before adding a command to your config, try running it in a Devin session to make sure it works. This is faster than waiting for a full build cycle.

​
Common errors quick reference

ErrorLikely causeFix
command not foundTool not installed or not on PATHAdd to initialize, or add to PATH via $ENVRC
Permission deniedMissing sudoUse sudo apt-get install for system packages
npm ERR! 404Private package, no authAdd registry auth token in maintenance (examples)
E: Unable to locate packageapt-get update not run firstAdd sudo apt-get update -qq before apt-get install
TimeoutSlow install or interactive promptMove to initialize; add -y and DEBIAN_FRONTEND=noninteractive
Empty config files after session startCredentials written in initializeMove credential steps to maintenance
Build succeeds but session is brokenmaintenance command fails at session startTest your maintenance commands manually in a session

​
Migrating from interactive setup

If you’re currently using the legacy interactive setup (the step-by-step wizard), you can migrate to declarative configuration for better reproducibility and multi-repo support.

​
How migration works

The legacy setup and declarative configuration each produce their own machine image. Sessions use one or the other — never a hybrid. An org-level toggle called “Use legacy machine snapshot” controls which image is used:
  • Toggle ON (default) — all sessions use the legacy snapshot. No disruption.
  • Toggle OFF — all sessions use the declarative snapshot.
This means you can configure and test the declarative setup in parallel while everyone else continues working with the legacy snapshot.

​
Migration steps

1

Prepare your configuration

Note the commands from your current interactive setup — you’ll map them to YAML sections:
Legacy wizard stepDeclarative equivalent
Git pullAutomatic (built-in)
Configure secretsSecrets (unchanged)
Install dependenciesinitialize section
Maintain dependenciesmaintenance section
Set up lintknowledge entry with name lint
Set up testsknowledge entry with name test
Run local appknowledge entry with name startup
Additional notesknowledge entry with name notes
2

Write your YAML

Go to Settings > Devin’s Environment and select your repository. Map your legacy commands:
# Legacy "Install Dependencies" → initialize
initialize: |
  nvm use 18
  npm install -g pnpm

# Legacy "Maintain Dependencies" → maintenance
maintenance: |
  pnpm install

# Legacy "Set up lint/tests/app/notes" → knowledge
knowledge:
  - name: lint
    contents: |
      pnpm lint
  - name: test
    contents: |
      pnpm test
  - name: startup
    contents: |
      pnpm dev (port 3000)
  - name: notes
    contents: |
      Always run lint before committing.
Or simply start a Devin session and ask it to set up the repo — Devin can auto-generate the configuration for you.
3

Save and wait for the build

Save your configuration. A build starts automatically. Monitor progress in Build History. Builds are free — they don’t cost ACUs.
4

Test before switching

Before migrating everyone, test the declarative setup on individual sessions using the manual override. This lets you (or whoever is iterating on the config) use the declarative snapshot while everyone else stays on the legacy snapshot.Iterate on the configuration until the declarative setup reaches full parity with your legacy environment.
5

Switch over

Once confident, toggle OFF “Use legacy machine snapshot” in your org settings. All new sessions will now use the declarative snapshot.
Interactive authentication flows (e.g., AWS SSO browser login, OAuth flows that require a browser) cannot be replicated in the declarative format. If your legacy setup uses browser-based authentication, you’ll need to convert those flows to headless alternatives (API keys, service account tokens, etc.) before migrating. Add credentials to Secrets and reference them in your maintenance section.

​
Enterprise migration

For enterprises with multiple organizations:
  1. Configure the enterprise-level YAML first — shared infrastructure like VPN, certificates, and proxy settings.
  2. Migrate one org at a time. Each org has its own legacy toggle, so you can migrate progressively without affecting other teams.
  3. Consider a test org. For large enterprises, create a dedicated test organization to validate the declarative configuration before rolling out to production orgs.
  4. Use Devin for scale. Devin can configure repos via parallel sessions — launch one session per repo and Devin will auto-generate configuration proposals. This works well for onboarding 10–100+ repos.

​
What happens to my old snapshot?

Your old snapshot is preserved. If the new declarative build fails, Devin falls back to the most recent successful snapshot (which may be your legacy one). You can also restore previous snapshots via Build History.

​
Key differences

FeatureLegacy (interactive)Declarative (YAML)
ReproducibilityStateful — snapshots accumulate changes over timeFully reproducible from YAML
Multi-repoOne repo at a timeMultiple repos in one build with concurrent cloning
MaintenanceManual “maintain dependencies” stepsAutomatic — maintenance runs at session start
Enterprise/org layersNot supported3-tier hierarchy (Enterprise → Org → Repo)
Devin suggestionsIn-wizard onlyIn-session — Devin can suggest config updates
CostWizard sessions used ACUsSetup sessions ~1–3 ACUs; builds are free

​
Frequently asked questions

​
General

What happens if I run a session on a repo that isn’t set up? Devin will still work — it just has to figure out your project from scratch each time. That means spending time installing dependencies, discovering how to build and test, and guessing at conventions. Sessions take longer and cost more ACUs. Setting up your environment means Devin starts every session pre-configured and ready to go. How long does a build take? Typically 5–15 minutes depending on the number of repos and dependency sizes. Builds time out after 2 hours. How much does this cost? Builds are free — they don’t cost ACUs. If you use a Devin session to set up a repo (e.g., asking Devin to generate your configuration), that session typically costs 1–3 ACUs. Once the configuration is saved, all subsequent builds from it are free. Can I use both legacy and declarative setup? An org uses one mode at a time, controlled by the “Use legacy machine snapshot” toggle. You can configure the declarative setup in parallel while the toggle is still on (legacy mode), then switch over when ready. See the migration guide for details. Can I test declarative setup without affecting other users? Yes. Use the manual override on individual sessions to temporarily use the declarative snapshot while everyone else stays on the legacy snapshot. For enterprises, you can also create a dedicated test organization. What happens if my build fails? Devin uses the most recent successful snapshot. A failed build doesn’t break existing sessions. When should I use initialize vs maintenance? Use initialize for one-time tool installations (apt-get install, language runtime setup, global CLI tools). Use maintenance for dependency installation that needs to stay fresh (npm install, pip install, uv sync). How do I add environment variables? Write them to $ENVRC: 
initialize: |
  echo "MY_VAR=value" >> $ENVRC
Can I install system packages? Yes, use sudo apt-get install in your initialize section. Always use DEBIAN_FRONTEND=noninteractive and the -y flag to prevent interactive prompts. What if I need different Node versions for different repos? Use nvm in your repo-level config: 
initialize: |
  nvm install 18
  nvm use 18
Are interactive authentication flows supported? No. Browser-based authentication (like AWS SSO login, OAuth flows requiring a browser window) cannot be replicated in the declarative format. Convert these to headless alternatives — use API keys, service account tokens, or other credential-based approaches and store them in Secrets. There is currently no workaround for workflows that strictly require browser-based SSO. These repos should continue using the interactive setup until headless alternatives are available.

​
Build-specific

What does “partial success” mean? The core build (enterprise + org setup + cloning) succeeded, but one or more repository-level setups failed. Sessions will work, but the failed repos may not have their dependencies installed correctly. Why was my build cancelled? A newer build was triggered before your build completed. Only the latest build runs; older queued builds are cancelled automatically. Does changing one repo’s config rebuild everything? Yes — a build creates a single machine image containing all configured repos. Any change to any configuration triggers a full rebuild. Can I rollback to a previous build? Yes, via Build History in the Environment Settings. You can restore any previous successful snapshot. How many repos can I include? Up to 10 repos are cloned concurrently during a build. There’s no hard limit on total repos, but more repos mean longer builds. Devin can configure repos at scale via parallel sessions — launch one session per repo for 10–100+ repos.

​
Enterprise-specific

Who can edit enterprise-level configuration? Enterprise admins only. Org admins can edit org-wide and repo-level config. Regular members can edit repo-level config if they have the ManageOrgSnapshots permission. See Enterprise Environment Setup for the full permissions table. Does changing enterprise config rebuild all orgs? Yes. An enterprise-level change triggers builds for every organization in the enterprise. Can different orgs have different configurations? Yes. Each org has its own org-wide config and repo-level configs. The enterprise config is shared and additive — it runs before each org’s config. Can lower-level configs override higher-level ones? No. The hierarchy (Enterprise → Org → Repo) is strictly additive. Each level’s commands run in sequence after the previous level finishes. Lower levels cannot prevent or modify what higher levels configure. Can enterprise-level config clone repositories? No. Repository cloning requires org-level access. Enterprise-level config can install shared tools and infrastructure, but repo cloning must be configured at the org or repo level.

​
Known limitations

  • No build preview/sandbox — every config change triggers a full build. Test commands in a session first.
  • Serial repo setup — repository-level setup runs one repo at a time (alphabetical order). Large numbers of repos mean longer builds.
  • No conditional logic in YAML — the format doesn’t support if/else. Use shell conditionals in your commands if needed (e.g., [ -f package.json ] && npm install).
  • No build log search — build logs must be scrolled manually. Use named steps to make failures easier to find.

​
Next steps