Skip to main content
Start with the Runloop Quickstart to use the examples below.

​
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. 
blueprint = await runloop.blueprints.from_id(blueprint_id="{blueprint_id}")
logs = await blueprint.logs()
for log in logs.logs:
    print(f"{log.level}: {log.message}")
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: 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.

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