Troubleshooting
Follow this guide in case you are experiencing unexpected behaviour or facing some errors in the module work.
Since Laravel Sanctum requires a specific configuration for your application, your production might work differently in comparison to a local development environment.
On this page, you can find a description of the most common issues raised on GitHub and how to solve them by adjusting either your Laravel or Nuxt application configurations.
Common problems
First of all, if you experience any unexpected behaviour, we recommend enabling logLevel: 5
in your nuxt.config.ts
to get more details in SSR (server console) or CSR (browser console) output. For more details about logging, please refer to this page - Logging.
In case of misconfiguration on either Nuxt or Laravel side, you may experience:
Authentication state reset on page reload
Difference between CSR and SSR state
Errors while trying to log in
Failing subsequent requests after successfully logging in
Before searching for a solution to your problem, we highly recommend double-checking your configuration and ensuring that the cache is cleared and your runtime reflects the latest changes.
Works on client-side (CSR), but not on server-side (SSR)
If you have SSR enabled, our module sends some of the requests on plugin initialisation before returning content to the client, which means we have to proxy some initial request data which might work differently on the server side. For example, to fetch user identity we are passing cookies from the initial client request.
Since CSR and SSR requests are sent from different environments, you have to ensure that your API is accessible from both of them and Laravel allow accepting requests from CSR/SSR hosts.
If you use a Docker container, make sure that the sanctum.baseUrl
in your nuxt.config.ts
is accessible from both your web browser and the Nuxt container. We recommend using a domain name as the name of the container in the virtual network to avoid side effects. You can check the example here - breeze-api.
In case you use additional software to set up virtual domains for development purposes (e.g. Laravel Valet, Homestead, dnsmasq, etc), you may end up with incorrect DNS resolving by Node. We recommend to use localhost
domain with different ports instead.
Request blocked by CORS policy
Incorrect CORS configuration on the Laravel side can cause the following problem
Access to fetch at 'X' from origin 'Y' has been blocked by CORS policy: The 'Access-Control-Allow-Origin' header has a value 'Z' that is not equal to the supplied origin. Have the server send the header with a valid value, or, if an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with CORS disabled.
In this case, your Nuxt application is calling API endpoint X from host Y, which is not the same as Z configured as allowed_origins
in Laravel's config/cors.php
.
If you are using Laravel Breeze, then adjusting FRONTEND_URL
environment variable would be enough.
Unable to load user identity from API (Code 500 / 403)
If Nuxt cannot retrieve user identity on plugin initialization, that means that either your API is not reachable or there is an endpoint misconfiguration.
For example, the following error means that fetch
could not find a host with laravel.test
URL due to network problems.
You should double-check:
URL exists and is reachable,
schema is chosen correctly (http/https),
API port is set correctly (e.g. 80, 8080, 8000, 3000)
a Docker container is up and running (if applicable),
artisan serve
is usinglocalhost
instead of127.0.0.1
(if applicable)
Also, while working locally with enabled SSL, you may face the following error:
To enable HTTPS protocol, you might need to set an environment variableNODE_TLS_REJECT_UNAUTHORIZED=0
.
User is not authenticated on plugin initialization (Code 401)
With enabled logging, you can check your Nuxt logs to find errors and warnings about the reason for the 401 response. For example, if you see the following message there:
then you should check your SANCTUM_STATEFUL_DOMAINS
environment variable on the Laravel side. If you have a domain different than your Nuxt application is hosted on, it can cause an issue.
CSRF mismatch (Code 419)
In the logs you can see this entry - CSRF token mismatch, check your API configuration
. This error usually occurs if your API returns a 419 status code, meaning Laravel expects a different cookie value which in most cases can be solved by adjusting the SANCTUM_STATEFUL_DOMAINS
or SESSION_DOMAIN
environment variables in your Laravel application.
Keep in mind, that Laravel supports cookies only from the same TLD, meaning you cannot call your API from a different domain. For instance:
frontend app - https://myapp.com
backoffice app - https://admin.myapp.com
Laravel API - https://api.myapp.com
In this setup, SESSION_DOMAIN
should be .myapp.com
and SANCTUM_STATEFUL_DOMAINS
should be myapp.com,admin.myapp.com
.
If you want to use token
authentication, make sure to remove your frontend application from stateful domains to avoid CSRF-check middleware.
Missing headers in the API request
If you use routeRules
and do not see Nuxt passing some of the expected headers to your Laravel API, it might be because of proxying behaviour, which is a bit different from the direct fetch request.
Make sure that you also define supported headers in your nuxt.config.ts
like this:
If you could not find anything useful, please check the Issues section on GitHub or feel free to create a new one!