Troubleshooting

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/utils/get-config.ts
• packages/plugins/legal-consent/src/index.ts
• packages/adapters/convex/test/schema.test.ts
• packages/adapters/convex/src/generate-schema/generate-schema-builder.ts
• packages/internal/bun-build/src/build.ts
• packages/cli/src/utils/add-svelte-kit-env-modules.ts
• packages/plugins/legal-consent/tests/legal-consent.test.ts

This document provides guidance for diagnosing and resolving common issues encountered when using the Better Auth Kit, particularly with the CLI, plugins, and adapters. It covers configuration loading problems, API error handling, and schema generation debugging.

The primary areas for troubleshooting involve ensuring the CLI can correctly locate and parse your authentication configuration, understanding how plugins validate requests and return specific error codes, and debugging the schema generation process for adapters like Convex. Careful attention to CLI error messages and API responses is key to resolving issues efficiently.

CLI Configuration Loading

A frequent source of problems is the CLI's inability to find or parse the better-auth configuration file. The getConfig utility is responsible for this process, and understanding its behavior can help resolve these issues.

Sources: packages/cli/src/utils/get-config.ts

Configuration Search Process

The CLI automatically searches for your configuration file in several common locations if a specific path is not provided.

This diagram illustrates the logic flow for locating and loading the configuration file.

The CLI searches for the following files in common framework directories (e.g., src/, app/, ./):

• auth.ts
• auth.tsx
• auth.js
• auth.jsx
• auth.server.js
• auth.server.ts

Sources: packages/cli/src/utils/get-config.ts:15-22

Common Configuration Errors

Missing Auth Export

Your configuration file must export the betterAuth instance, either as a default export or as a named export auth. If not, the CLI will fail.

// packages/cli/src/utils/get-config.ts:109-115
if (!config.auth && !config.default) {
    if (shouldThrowOnError) {
        throw new Error(
            `Couldn't read your auth config in ${resolvedPath}. Make sure to default export your auth instance or to export as a variable named auth.`,
        );
    }
    // ... logs error and exits
}

Sources: packages/cli/src/utils/get-config.ts:109-118

server-only Import Issue

The CLI's configuration loader (c12 with jiti) cannot resolve files that import server-only. If your auth config file contains import "server-only", you must temporarily remove it before running CLI commands.

// packages/cli/src/utils/get-config.ts:160-171
if (
    typeof e === "object" &&
    e &&
    "message" in e &&
    typeof e.message === "string" &&
    e.message.includes(
        "This module cannot be imported from a Client Component module",
    )
) {
    if (shouldThrowOnError) {
        throw new Error(
            `Please remove import 'server-only' from your auth config file temporarily. The CLI cannot resolve the configuration with it included. You can re-add it after running the CLI.`,
        );
    }
    // ... logs error and exits
}

Sources: packages/cli/src/utils/get-config.ts:160-171

SvelteKit Environment Modules

The CLI attempts to create mock modules for SvelteKit's $env/* imports to prevent loading errors. This process filters process.env based on PUBLIC_ prefixes. Issues with environment variables in your config might relate to this mechanism.

Sources: packages/cli/src/utils/add-svelte-kit-env-modules.ts:1-53

Plugin and API Errors

Plugins often introduce new validation logic that can result in API errors. Understanding these errors is crucial for debugging client-side interactions.

Example: Legal Consent Plugin

The @better-auth-kit/legal-consent plugin adds checks to the sign-up flow, requiring users to accept various policies. If a required consent is missing from the request body, the plugin throws an APIError with a specific error code.

Sources: packages/plugins/legal-consent/src/index.ts

The following sequence diagram shows how the legalConsent plugin intercepts a sign-up request and returns an error if the Terms of Service are not accepted.

Legal Consent Error Codes

The plugin defines a set of error codes that are returned in the API error response body.

Error Code	Description
TOS_NOT_ACCEPTED	TOS must be accepted
PRIVACY_NOT_ACCEPTED	Privacy must be accepted
AGE_NOT_ACCEPTED	Age must be accepted
MARKETING_NOT_ACCEPTED	Marketing must be accepted
COOKIE_NOT_ACCEPTED	Cookie must be accepted

Sources: packages/plugins/legal-consent/src/index.ts:98-104

Convex Schema Generation

When using the Convex adapter, the CLI generates a schema.ts file by merging the base better-auth schema with schemas from your plugins and any existing, user-defined tables. Errors in this process can lead to an invalid Convex schema.

Sources: packages/adapters/convex/src/generate-schema/generate-schema-builder.ts, packages/adapters/convex/test/schema.test.ts

Schema Generation Flow

The schema generation process involves parsing the existing schema file, converting plugin schemas to the Convex format, and merging them.

Debugging Schema Mismatches

The test suite for schema generation provides a useful debugging pattern. If a generated schema does not match the hard-coded expected output, the test logs both versions to the console, allowing for a direct comparison to identify discrepancies.

// packages/adapters/convex/test/schema.test.ts:70-76
if (generate_schema !== hard_coded_schema) {
    console.log(`\n\n\n--------------------------------- Generated:`);
    console.log(generate_schema);
    console.log(`--------------------------------- Hard-coded:`);
    console.log(hard_coded_schema);
    console.log(`---------------------------------\n\n\n`);
}
expect(generate_schema).toBe(hard_coded_schema);

This technique can be manually applied if you suspect the CLI is generating an incorrect schema. Run the generation and compare the output to what you expect.

Sources: packages/adapters/convex/test/schema.test.ts:70-77

Build and Development

The internal build scripts use Bun.build and provide simple console feedback on success or failure, including the time taken. When running in development mode (bun run dev), the scripts watch for file changes in the src directory and trigger a rebuild automatically, logging which file triggered the change.

Script	Functionality
build	Performs a one-time production build (minified, sourcemaps).
build-dev	Watches src directory for changes and triggers a rebuild automatically.

Sources: packages/internal/bun-build/src/build.ts:12-34, packages/internal/bun-build/src/build-dev.ts:7-22

If a build fails, the logs from Bun.build are printed to the console, which should indicate the source of the error.

// packages/internal/bun-build/src/build.ts:25-32
if (res.success) {
    console.log(
        `${chalk.greenBright("Success!")}`,
        chalk.gray(`${Date.now() - start}ms`),
    );
} else {
    console.error(
        `${chalk.redBright("Failed!")}`,
        chalk.gray(`${Date.now() - start}ms`),
    );
}

Sources: packages/internal/bun-build/src/build.ts:25-32