Guide

Troubleshooting

Common problems and how to fix them.

spin new cannot find the template

"my-template" is not a local path, git URL, or pinned name

Check that:

  • The path starts with /, ./, ~/, or is an absolute path.
  • The git URL starts with http://, https://, git@, git://, or ssh://.
  • The pinned name appears in spin list.
  • The registry shorthand is registered (spin registry list) and the template exists in that registry.

Pinned template missing on disk

spin new: pinned "go-cli-template" missing on disk at /home/me/.config/spin/templates/go-cli-template

The cache was deleted or moved. Re-pin the template:

spin remove go-cli-template --purge
spin add https://github.com/example/go-cli-template.git

Post-hook fails

spin new writes the rendered files, then runs [[post]] steps. If a post-hook fails, the files are already on disk. Fix the template or your environment, then re-run the failed command manually in the project directory.

Git clone fails with exit status 128

Common causes:

  • The repository does not exist or is private.
  • The network is unreachable.
  • GIT_TERMINAL_PROMPT=0 disables password prompts; use SSH keys or a personal access token.

Test the clone directly:

GIT_TERMINAL_PROMPT=0 git clone --depth=1 <url> /tmp/test-clone

Registry shorthand not found

alias "official" not registered

Check that:

  • The alias is registered: spin registry list.
  • The registry has a templates/go-cli.toml file.
  • The id inside go-cli.toml matches the filename.

spin search returns nothing

  • Verify the registry is registered: spin registry list.
  • Run spin registry update <alias> to refresh a git registry.
  • Check that the registry contains registry.toml and templates/*.toml.

Performance

spin is designed to be fast enough that caching is unnecessary:

  • spin search reads local TOML files; it does not hit the network.
  • spin new clones once per template; pinned templates reuse the local cache.
  • spin update only touches the templates you ask it to.

If a registry has hundreds of templates, spin search may take a moment the first time. There is no background indexing; each run scans the registry directories.

Still stuck?

Run with --dry-run to see what spin new would write without changing files:

spin new myapp --template <spec> --dry-run

Use --print-params to inspect how CLI flags are parsed:

spin new myapp --template <spec> --print-params --param key=value

Manage registries

Register, list, update, and remove template registries.

Build your first template

Create a spin template from scratch. Write a manifest, add params, write template files, add hooks, test it, and publish it.