Troubleshooting

Common failure modes and fixes.

”ntl: command not found” after install step succeeded

The integration installs netlify-cli globally and prepends the npm-global bin directory to the current process’s PATH. If your runner mounts a custom npm prefix, set PATH explicitly before running aspire deploy:

export PATH="$(npm config get prefix)/bin:$PATH"
aspire deploy

“401 Unauthorized” during deploy

The auth token resolved at deploy time is invalid or expired.

• Inspect which source the pipeline used — it logs an INFO line if the token came from the explicit parameter, or a WARN line if both the parameter and NETLIFY_AUTH_TOKEN were set with different values.
• Regenerate a new token at app.netlify.com/user/applications.

”site not found” after enabling CreateSite

CreateSite must be a non-empty, whitespace-free string. The pipeline now skips the create-site path when CreateSite is empty or whitespace, so an unset value falls back to Site resolution.

”The deploy directory ‘dist’ has not been found”

The directory-only overload PublishAsNetlifySite("dist", ...) (and the full options form with NoBuild = true) deploys a prebuilt folder as-is — it does not build the site. If nothing produced that folder first, the Netlify CLI fails with:

Error: The deploy directory "…/dist" has not been found. Did you forget to run 'netlify build'?

Wire the build into the AppHost so the deploy pipeline’s “Run npm commands” step produces the directory before deploying:

builder.AddJavaScriptApp("astro", "../astro")
    .WithNpmRunCommand("build")   // runs `npm run build` during `aspire deploy`
    .PublishAsNetlifySite("dist", authToken);

Match the script name and Dir to your framework (e.g. Next.js static export uses out, Angular uses dist/<project>/browser).

Deploy succeeds but the site still serves the old build

PublishAsNetlifySite("dist", ...) deploys the directory as-is (NoBuild = true). Make sure the site is rebuilt before it’s deployed — the simplest way is to add .WithNpmRunCommand("build") to the app so the pipeline rebuilds on every aspire deploy. The AllFrameworks.AppHost sample shows the typical pattern.

TypeScript AppHost: publishAsNetlifySite is missing from .aspire/modules/aspire.mjs

The integration must be referenced in aspire.config.json and the TypeScript project must be restored. Run:

aspire restore

If exports still don’t appear, make sure the version pinned in your aspire.config.json is at least 13.4.x.

Aspire dashboard shows the deploy step as orange but no error

The pipeline emits a warning when the auth resolution detects two sources of truth. Check the dashboard’s pipeline log for a line like "Both an authToken parameter and NETLIFY_AUTH_TOKEN are set..." — that’s a heads-up, not a failure. The parameter wins per precedence.

Where state lives

Per-deploy state files are written to:

~/.aspire/deployments/<sha256-of-AppHost-csproj-name>/<environment>.json

CI workflows can cache and restore this directory to keep created site IDs across runs.