​
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. 
curl -X GET 'https://api.runloop.ai/v1/blueprints/{blueprint_id}/logs' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY"
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: 
[
  {
    "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: Local Build Testing

If the logs don’t reveal an obvious problem, you may want to build the Docker image locally. This can help identify issues specific to your development environment or configuration.

​
2.1 Obtain the Dockerfile

Use the preview endpoint to get the full Docker configuration: 
curl -X POST 'https://api.runloop.ai/v1/blueprints/preview' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $RUNLOOP_API_KEY" \
  -d '{
  "name": "ai-dev-environment",
  "dockerfile": "FROM runloop:runloop/prod-ubuntu-dnd-arm64\nRUN apt-get update && apt-get install -y cowsay\n"
}' | jq -r '.dockerfile' > Dockerfile.runloop
This command uses jq to extract the Dockerfile from the response and save it to a file named Dockerfile.runloop.

​
2.2 Build Locally

With your Dockerfile.runloop ready, you can test and debug the build locally: 
docker build --build-arg GH_TOKEN_0="$GH_TOKEN" -f Dockerfile.runloop -t local-blueprint-img .

​
Step 3: 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.

​
Step 4: Seeking Additional Help

If you’re still encountering issues after following these steps:
  1. Review the Runloop Documentation 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.