Lucia v3

Troubleshooting

Here are some common issues and how to resolve them. Feel free to ask for help in our Discord server.

User and Session are typed as any

Make sure you've registered your types. Check that the typeof lucia is indeed an instance of Lucia (not a function that returns Lucia) and that there are no TS errors (including @ts-ignore) when declaring Lucia. Register must be an interface, not a type.

import { Lucia } from "lucia";

const lucia = new Lucia(adapter, {
	// no ts errors
});

declare module "lucia" {
	interface Register {
		Lucia: typeof lucia;
	}
}

Also check that you're passing typeof lucia and not typeof Lucia (notice the capitalization - lucia is an instance of class Lucia).

Session cookies are not set in localhost

By default, session cookies have a Secure flag, which requires HTTPS. You can disable it for development with the sessionCookie.attributes.secure configuration.

import { Lucia } from "lucia";

const lucia = new Lucia(adapter, {
	sessionCookie: {
		attributes: {
			secure: !devMode // disable when `devMode` is `true`
		}
	}
});

Can't validate POST requests

Check your CSRF protection implementation. If you're using the code provided by the documentation, check the Origin and Host header. The hostname must match exactly. You can add additional domains to the array to allow more domains.

import { verifyRequestOrigin } from "lucia";

verifyRequestOrigin(originHeader, [hostHeader, "api.example.com" /*...*/]);

crypto is not defined

You're likely using a runtime that doesn't support the Web Crypto API, such as Node.js 18 and below. Polyfill it by importing webcrypto.

import { webcrypto } from "node:crypto";

globalThis.crypto = webcrypto as Crypto;