Azure Static Web App - Adding a Linked Backend API fails for next.js app

Question

I have tried multiple times now to add a linked backend to my next.js app in azure static web apps. I allow the static web app to create the new web app & app service. The operation goes through successfully. For a brief period of time I will see 'Web App' under Backend Type and the correct resource under Backend Resource Name, but then it quickly reverts to what you see here.

The backend does not function and I cannot hit a healthcheck api endpoint on the web app resource directly, from a curl request, from my next.js app, or any other way I have tried. I then have to unlink the backend and wait for 30-60 minutes for something in the cache to clear to reset my website back to working.

At this point I've exhausted everything I believe I can try on my end. I'd really like to get a linked backend web app of S1 tier setup.

Answer 1

1. Check the SWA Plan

Ensure your SWA is on the Standard or Dedicated plan. The “Bring your own API” feature is not available on the free plan.

2. Configure the GitHub Workflow File

In the GitHub workflow file (azure-static-web-apps-<name>.yml), set the api_location to an empty string:

api_location: ""

This tells SWA not to manage internal functions and allows you to link an external backend.

3. Remove Managed Functions (If Any)

If your SWA already has managed functions, remove them before linking an external backend. This can be done in the Azure portal or the workflow file.

4. Link the Backend in the Azure Portal

In the Azure portal:

• Go to your SWA.
• Select APIs in the navigation menu.
• Click Link in the production line.
• Choose App Service as the backend type.
• Select your subscription, resource name, and desired App Service slot.
• Click Link.

This will link your backend to the /api path of the SWA.

5. Check Authentication Configuration

After linking, SWA creates an identity provider called “Azure Static Web Apps (Linked)” in the App Service. If you want the backend to be publicly accessible, remove this identity provider in the App Service authentication settings.

Possible Errors and Solutions

• Error: “Cannot link backend with a preexisting Azure Static Web Apps configuration”
  This error may occur if the SWA already has a managed functions configuration. Ensure you remove any previous configurations before linking a new backend.
• Backend Not Working After Linking
  If the backend is not working after linking, wait for 30 to 60 minutes for configurations to propagate. Also, check if the backend health endpoint is accessible directly (without going through SWA) to diagnose connectivity issues.

Answer 2

Hi Kyle,

It seems the issue is caused by a misconfiguration in linking external backends for Next.js apps in Azure Static Web Apps. In the second image, the Backend Type is missing, and the Backend Resource Name is incorrectly formatted, which is likely causing the problem.

The root issue is that Next.js internal API routes conflict with Azure SWA's routing, causing Azure to send /api/ requests to the external App Service while Next.js handles them internally.

• Update your Next.js configuration to change the API routes' prefix in next.config.js, so they stay in the /api folder but are exposed at /backend-api endpoints.

module.exports = {
  rewrites: async () => {
    return [
      {
        source: '/backend-api/:path*',
        destination: '/api/:path*',
      },
    ];
  },
};

• Configure your Azure Static Web App to route only specific API calls to the external backend by using the Azure CLI or REST API to set a custom route pattern, so only /external-api/* requests go to your App Service, and Next.js handles its own API routes.

az staticwebapp backend link --name "buildapack-staticwebapp" --resource-group "your-resource-group" --backend-resource-id "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Web/sites/buildapack-webapp" --backend-region "your-region" --patterns "/external-api/*"

• Update CORS settings on your App Service to allow requests from your Static Web App domain by adding its URL to allowed origins and enabling credentials if authentication is needed.
• Check the authentication flow by ensuring the backend App Service has Azure AD authentication enabled and the Static Web App forwards authentication headers to the backend.

After making these changes, deploy the updated Next.js configuration, unlink the existing backend, wait 15-20 minutes for cached configurations to clear, link the backend with the specific API route pattern, and test with a simple health endpoint.

Please refer to the following documents for Next.js with Azure Static Web App and configuration:

https://learn.microsoft.com/en-us/azure/static-web-apps/deploy-nextjs-hybrid#create-a-static-web-app

https://learn.microsoft.com/en-us/azure/static-web-apps/configuration#routes

Answer 3

Hi! Thanks for providing such detailed context, that really helps to narrow things down.

From your description, it looks like your linked backend is being reset due to how the Azure Static Web Apps (SWA) pipeline is configured or how the backend is being linked. Here’s a breakdown of what’s happening and step-by-step guidance on how to fix it:

---

Problem Areas and How to Fix Them

1. api_location: "" in your azure-static-web-apps.yml

• What’s happening: Setting api_location to an empty string tells Azure SWA that no API is part of the build. This causes the backend to default to none, which may override your manually linked backend when the pipeline runs.
• How to fix: If you’re using a linked backend (external function app or API), do not leave api_location blank. Instead:
  • Either remove the api_location line completely (if not required for build)
  • Or point it to a placeholder directory (e.g., api), even if unused
  • Best practice: Set api_location to a real or dummy API project that doesn’t interfere with your external backend link, or manage the backend via ARM template or CLI after deployment

2. DevOps Pipeline Overwrites Backend Link

• What’s happening: Even though you manually link a backend via the portal, each new deployment via Azure DevOps may override this link, especially if the api_location isn’t properly set
• How to fix:
  • After linking the backend in the portal, consider persisting the link using the Azure CLI or ARM template as part of the pipeline
  • Example CLI command:

    
        az staticwebapp appsettings set \
    
          --name <your-swa-name> \
    
          --resource-group <your-rg> \
    
          --setting-names backendResourceId=/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.Web/sites/<function-app-name>
    
    

  • This ensures the link persists across pipeline executions

3. Backend Should Not Be Public

• What’s happening: You want the backend to only be accessible from the Static Web App, but by default, linked backends can be public unless you apply additional security
• How to fix:
  • Use a VNet with a private endpoint if the backend is in a Function App (Premium Plan)
  • Or restrict access using CORS or IP filtering, allowing only the SWA outbound IPs
  • Alternatively, enable Easy Auth or use Managed Identity so only the SWA can call the backend with a token

4. It Works with Built-in Next.js API but Breaks When Linking Backend

• What’s happening: When using the built-in Next.js API (/api folder), everything works fine. But using the "Link new Backend" wizard breaks the setup
• How to fix:
  • Confirm that once you link the backend, the /api/* route is proxied correctly to the backend function app
  • Check your routes.json or any API proxy configuration in your SWA (under /staticwebapp.config.json) to ensure that API requests are being forwarded correctly

5. Manual Linking Reverts Back

• What’s happening: After linking in the portal, it shows temporarily as connected, then reverts
• How to fix:
  • This is most likely due to DevOps overwriting the configuration on the next deploy
  • As mentioned above, automate the backend link in your pipeline using the Azure CLI
  • Also ensure your azure-static-web-apps.yml does not contain conflicting configuration that causes the portal settings to be reset