Logging

Use BP_AUTH_LOG_LEVEL to control the verbosity of Blueprint Auth's console logs. Entries have a blueprint-auth [LEVEL] prefix.

Configure log levels

Set the environment variable in the application running Blueprint Auth, for example in your local environment file:

BP_AUTH_LOG_LEVEL=DEBUG

Value	Messages emitted
NONE	None
ERROR	Errors
WARN	Warnings and errors
INFO	Informational messages, warnings, and errors
DEBUG	All messages, including debug details

Values are case-insensitive: debug and DEBUG work alike. An unset or invalid value falls back to INFO.

Diagnose auth errors

1. Reproduce the failing auth operation and inspect the application's server logs. Look for blueprint-auth entries around the failure.
2. Use the error code, message, and any Cause: text to identify the failing step. Check the relevant auth configuration or upstream failure rather than relying on severity alone.
3. If you need more context, temporarily set BP_AUTH_LOG_LEVEL=DEBUG in a controlled local or test environment, restart the application, and reproduce once with test data.
4. Restore your usual log level after investigating. Remove sensitive details before sharing an excerpt.

Do not assume logs are fully redacted. Causes and debug details can contain sensitive data. Avoid logging or sharing cookies, tokens, credentials, or personally identifiable information (PII). If production debugging is necessary, keep it brief and restrict log access and retention.

Custom GraphQL error severity

Use customization.getGraphQLErrorLogLevel to change the severity when createGraphQLHandler converts a caught failure into an auth log entry. For example, downgrade a known business outcome while leaving other failures at error.

Reuse your existing authConfig and merge its customization options. This App Router handler treats one illustrative Kraken error message as expected; replace that condition with an outcome your application explicitly recognizes.

import { BlueprintAuthErrorCode } from "@krakentech/blueprint-auth";
import { createGraphQLHandler } from "@krakentech/blueprint-auth/server";
import { authConfig } from "@/lib/auth/config";

export const POST = createGraphQLHandler({
  ...authConfig,
  customization: {
    ...authConfig.customization,
    getGraphQLErrorLogLevel({ errorCode, cause }) {
      const isExpectedOutcome =
        errorCode === BlueprintAuthErrorCode.OperationGraphQLUnknown &&
        Array.isArray(cause) &&
        cause.some(
          (item: unknown) =>
            typeof item === "object" &&
            item !== null &&
            "message" in item &&
            item.message === "No meter point found",
        );

      return isExpectedOutcome ? "warn" : "error";
    },
  },
});

The synchronous callback has signature ({ message, errorCode, cause, source }) => "error" | "warn" | "info" | "debug" | undefined:

• message is a string and errorCode is the auth error code.
• source is always "blueprint-auth".
• cause is optional and typed as unknown. For a Kraken GraphQL error response, it contains the Kraken errors array. Other failures can have other shapes; narrow both the array and its entries before reading fields.

Return a lowercase level. Returning undefined or an invalid value falls back to error. Throwing also falls back to error and logs the callback failure. Without a callback, existing logging behavior is unchanged.

BP_AUTH_LOG_LEVEL still filters the selected level: a warn entry is hidden at ERROR, and NONE suppresses all levels. The callback changes logging only, not the response, HTTP status, or GraphQL error policy (none, ignore, or all). It does not change entries already logged before the handler catches the failure.