Netlify "site not found" (NETLIFY_SITE_ID) in CI

By Daniel Zoghalchali·Latchkey

The Netlify CLI cannot determine which site to deploy. CI has no .netlify/state.json link, so you must provide NETLIFY_SITE_ID (or --site) that matches a site the token can access.

What this error means

A netlify deploy step fails with "Error: site not found. Please rerun with --site" or reports that no site is linked.

Error: site not found. Please rerun "netlify link" or pass a --site flag

Common causes

No linked site in CI

The .netlify link is local and untracked, so a fresh checkout has no site association and no NETLIFY_SITE_ID.

A site ID the token cannot access

The provided ID belongs to a different team or no longer exists, so the API returns site not found.

How to fix it

Set NETLIFY_SITE_ID from site settings

1. Copy the API ID from Site settings, Site information.
2. Store it as a CI variable named NETLIFY_SITE_ID.
3. Expose it to the deploy step (the CLI reads it automatically).

env:
  NETLIFY_SITE_ID: ${{ vars.NETLIFY_SITE_ID }}
  NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}

Pass the site with --site

Alternatively pass the site ID or name directly to the deploy command.

netlify deploy --prod --site $NETLIFY_SITE_ID

How to prevent it

• Set NETLIFY_SITE_ID as a CI variable so deploys are deterministic.
• Use a token scoped to the team that owns the site.
• Do not rely on a local .netlify link in CI.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation