> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runloop.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Blueprint Builds

> Debug and fix your Blueprint builds in Runloop.

<Tip>Start with the [Runloop Quickstart](/docs/tutorials/quickstart) to use the examples below.</Tip>

## Step 1: Check Blueprint Logs

Start by examining the build process logs. Runloop builds a Docker image behind the scenes, and you can access these logs using the Blueprint logs endpoint.

<CodeGroup>
  ```python Python theme={null}
  blueprint = await runloop.blueprint.from_id(blueprint_id="{blueprint_id}")
  logs = await blueprint.logs()
  for log in logs.logs:
      print(f"{log.level}: {log.message}")
  ```

  ```typescript TypeScript theme={null}
  const blueprint = await runloop.blueprint.fromId('{blueprint_id}');
  const logs = await blueprint.logs();
  for (const log of logs.logs) {
    console.log(`${log.level}: ${log.message}`);
  }
  ```

  ```bash curl theme={null}
  curl -X GET 'https://api.runloop.ai/v1/blueprints/{blueprint_id}/logs' \
    -H "Authorization: Bearer $RUNLOOP_API_KEY"
  ```
</CodeGroup>

Replace `{blueprint_id}` with your actual Blueprint ID.

### Interpreting Log Output

The logs can help you identify specific build issues. Here's an example of what you might see:

```json theme={null}
[
  {
    "level": "info",
    "timestamp_ms": 1722357063912,
    "message": "fatal: could not read Password for 'https://$GH_TOKEN@github.com': No such device or address"
  },
  {
    "level": "info",
    "timestamp_ms": 1722357063915,
    "message": "error building image: error building stage: failed to execute command: waiting for process to exit: exit status 128"
  }
]
```

In this example, the error suggests an issue with GitHub authentication, possibly due to an invalid or missing token.

## Step 2: Common Issues and Solutions

Here are some common issues you might encounter and how to resolve them:

1. **Blueprint Not Found**:
   * If you're extending a blueprint from a public runloop blueprint, ensure you're using the correct prefix `runloop:runloop/<blueprint_name>`.
   * Ensure that the CPU architecture is compatible with the base image (ie. don't mix up `arm64` and `x86_64`).

2. **GitHub Authentication Errors**:
   * Ensure your `GH_TOKEN` is valid and has the necessary permissions.
   * Check that the token is correctly set in your environment variables.

3. **Package Installation Failures**:
   * Verify that your `launch_parameters.launch_commands` are correct and compatible with the base image.
   * Ensure you're using the correct package manager (apt for Debian-based images).

4. **CodeMount Issues**:
   * Double-check the repository name, owner, and access permissions.
   * Verify that the `install_command` is appropriate for your project.

5. **Resource Constraints**:
   * If the build is timing out or failing due to resource limits, consider optimizing your Dockerfile or increasing resource allocations.

6. **Incorrect user / UID**:
   * If you build a blueprint that needs to run as root (for example)
     and then start the devbox with a different user, the devbox will
     fail to start with a missing directory error. This is because the
     devbox is attempting to cd into a home directory that doesn't
     exist. To fix this issue, specify the UID and user in the
     launch\_parameters.

7. **CPU architecture mismatch**:
   * Some binaries and libraries are only available for specific CPU
     architectures. Blueprints allow you to specify a preferred CPU
     architecture. Starting a Devbox with the wrong CPU architecture
     will result in the Devbox failing to start up correctly.

8. **Devbox stuck initializing due to background processes in `launch_commands`**:
   * `launch_commands` waits for all STDOUT and STDERR output to complete before marking the devbox as running. If any command starts a background process (e.g., a server) without redirecting its output, the devbox will never transition to the `running` state.
   * Fix: redirect STDOUT and STDERR to a file or `/dev/null` for any background process:
     ```bash theme={null}
     # Instead of:
     "my-server start &"
     # Use:
     "my-server start > /tmp/server.log 2>&1 &"
     ```

## Step 3: Seeking Additional Help

If you're still encountering issues after following these steps:

1. Review the [Runloop Documentation](https://docs.runloop.ai) for any updates or known issues.
2. Reach out to Runloop support with:
   * Your Blueprint ID
   * The full logs from both Runloop and your local build attempts
   * A description of the steps you've taken to troubleshoot

By following this troubleshooting guide, you should be able to identify and resolve most issues with your Blueprint builds.