> ## 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.

# Template Error Handling

> Handle build failures, upload failures, and terminal template states.

Template builds can fail during file upload, base image import, build steps,
startup readiness, or publication. Catch typed SDK errors and inspect the
failure details before retrying.

## Blocking build

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
from nullspace import Template
from nullspace.errors import BuildError, FileUploadError

try:
    build = Template.build(Template.from_python_image("3.12"), "python-dev")
except FileUploadError as error:
    print(error)
except BuildError as error:
    if error.error_detail:
        print(error.error_detail.phase, error.error_detail.message)
```

## Background build

```python theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
build = Template.build_in_background(
    Template.from_python_image("3.12"),
    name="python-dev",
)
final = build.wait_until_terminal()
print(final.build.status)
```

Retry only after checking whether the failed phase is retryable. Authenticated
private base-image imports and local build-context uploads are intentionally
conservative about cache reuse.

Concept: [Create](../../concepts/create). API reference:
[startTemplateBuild](../../api-reference), [getTemplateBuildStatus](../../api-reference).