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

# Error handling

> Recover from build failures, upload failures, and terminal template states.

## Blocking build

<CodeGroup>
  ```python Python SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  from nullspace import BuildError, Template

  try:
      Template.build(builder, "broken-template")
  except BuildError as exc:
      print(exc)
      if exc.error_detail:
          print(exc.error_detail.phase, exc.error_detail.suggested_action)
  ```

  ```typescript TypeScript SDK theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  import { BuildError } from "@nullspace/sdk";

  try {
    await client.templates.builder()
      .fromPythonImage("3.12")
      .build({ name: "broken-template" });
  } catch (err) {
    if (err instanceof BuildError) {
      console.error(err.message);
    }
  }
  ```

  ```bash HTTP API theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
  # Terminal build failures arrive as an SSE entry with kind=error and
  # error_detail.code=build_error. Request-validation/blob failures return an
  # HTTP 400 before the stream starts. See the API reference for error_detail.
  curl -N -X POST "${NULLSPACE_API_URL}/v1/templates/build" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{"name": "broken-template", "base_image": "python:3.12"}'
  ```
</CodeGroup>

## Background build

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
build = Template.build_in_background(builder, "maybe-broken")
try:
    snapshot = build.wait_until_terminal()
    print(snapshot.build.status)
except BuildError as exc:
    print(exc.error_detail.phase if exc.error_detail else exc)
```

## Troubleshooting

| Symptom                            | Check                                                                                                                                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Build context upload fails         | Large local sources may need resumable file transfer and stable network access.                                                                                            |
| Dockerfile warning entries         | Native-backend unsupported Dockerfile instructions are ignored and logged with line numbers. BuildKit-backed Dockerfiles use BuildKit failure and progress output instead. |
| Machine cannot start from template | Check start command, readiness probe, and runtime envs.                                                                                                                    |
| Private registry pull fails        | Confirm registry auth helper and credential lifetime.                                                                                                                      |

## Related

* [Build logs](./build-logs)
* [Base images](./base-images)
* [Errors and types](../guides/python-sdk/errors-types)