testing & debugging

50 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Finding API errors in logs - database level errors query

Use the log explorer to find all API errors at the database level by filtering postgres_logs where error_severity matches 'ERROR|FATAL|PANIC' and user_name = 'authenticator'. The authenticator role represents the database API.

Finding API errors in logs - specific database error query

Use the log explorer to find a specific database error from the data API by filtering postgres_logs where sql_state_code matches the error code (e.g. '42501') and user_name = 'authenticator'.

Finding API errors in logs - specific API error query

Use the log explorer to find specific API errors by filtering edge_logs where status_code >= 300, path matches '^/rest/v1/', and proxy_status matches the relevant status code.

Counting API errors per path by hour in logs

Use the log explorer to count errors per path by hour by grouping edge_logs by timestamp_trunc(timestamp, hour), proxy_status, and path where status_code >= 300 and path matches '^/rest/v1/'.

Finding data API request from specific authenticated user in logs

Use the log explorer to find data API requests from a specific authenticated user by filtering edge_logs where path matches '^/rest/v1/' and sb.auth_user equals the user ID from the auth.users table.

Flask and Supabase client installation

Install Flask and the Supabase client library using pip install flask supabase. This provides the web framework and a convenient interface for working with Supabase from a Python app.

Python virtual environment setup for Supabase Flask app

Create a new directory, navigate into it, set up a virtual environment using python3 -m venv venv, and activate it with source venv/bin/activate.

Load environment variables in Python with python-dotenv

Install the python-dotenv package using pip install python-dotenv, then use load_dotenv() in your app to load variables from the .env file.

Flask app example with Supabase query

Complete Flask app code: import os, Flask, create_client and Client from supabase, APIError from postgrest, and load_dotenv. Initialize Flask app and Supabase client from environment variables. Add route that calls supabase.table('instruments').select("*").execute(), catches APIError with error.message, and returns HTML with instrument names from response.data. Run with app.run(debug=True) on http://localhost:5000.

macOS port 5000 conflict with Flask development server

On macOS, port 5000 is used by the AirPlay Receiver service. If the page doesn't load, turn AirPlay Receiver off in System Settings > General > AirDrop & Handoff, or run the app on another port with app.run(debug=True, port=5001).

supabase_flutter platform compatibility

The supabase_flutter package is compatible with web, iOS, Android, macOS, and Windows apps. Running on macOS requires additional configuration to set the entitlements.

Android internet permission for Supabase production

In production, add the android.permission.INTERNET permission to the android/app/src/main/AndroidManifest.xml file to allow the app to communicate with Supabase APIs. Add the line '<uses-permission android:name="android.permission.INTERNET" />' inside the manifest element.

Create Nuxt app with npx nuxi

Create a Nuxt app using the command `npx nuxi@latest init my-app`. For non-interactive shells, pass flags: `npx nuxi@latest init my-app --template minimal --no-gitInit --packageManager npm`.

Fetch data in Nuxt onMounted lifecycle

Fetch data in the `onMounted` lifecycle hook so the results appear after the page loads in the browser, avoiding server-side rendering issues.

Start Nuxt development server

Start the development server with `npm run dev` and navigate to http://localhost:3000 in the browser.

Create React app with Vite template

Run `npm create vite@latest my-app -- --template react` to create a new React app using the Vite template.

Start React development server

Run `npm run dev` to start the development server. The app will be accessible at http://localhost:5173 in a browser.

Create Vue app with npm init

Create a Vue app by running npm init vue@latest my-app from the command line.

Vue dev server default port

Running npm run dev in a Vue project starts the development server at http://localhost:5173 by default.

npm init vue scaffolds TypeScript by default

The npm init vue@latest command creates a TypeScript project by default. If a JavaScript-only project is chosen instead, use .js file extensions and drop the type import statements.

W3C trace context headers propagation through Supabase SDKs

The Supabase JS, Swift, Dart, and Python SDKs can attach W3C Trace Context headers (traceparent, tracestate, baggage) to outgoing requests. The resulting trace_id flows through Supabase services and appears in API Gateway and Edge Function logs, enabling end-to-end correlation of client-side spans with server-side logs across the network boundary.

JavaScript SDK trace propagation version requirement

@supabase/supabase-js version 2.106.0 or later supports trace propagation. As of version 2.112.0, the OpenTelemetry integration lives in an opt-in subpath that must be imported at the application entry point with: import '@supabase/supabase-js/tracing'

JavaScript SDK OpenTelemetry dependencies for trace propagation

@opentelemetry/api must be available at runtime, either installed directly or as a transitive dependency of a tracing SDK. A tracing SDK must register a W3C-compliant propagator with the OpenTelemetry API.

JavaScript SDK trace propagation subpath import behavior by version

On @supabase/supabase-js versions 2.112.0 and later, import '@supabase/supabase-js/tracing' at the application entry point to enable trace propagation. The subpath imports @opentelemetry/api directly, so the bundler includes it and module resolution fails if it isn't installed. On versions 2.106.0–2.111.x, the subpath doesn't exist and should not be imported; those versions load @opentelemetry/api dynamically and silently no-op when it's missing. If tracePropagation is enabled without the import on 2.112.0+, the SDK logs a one-time warning and sends requests without trace headers.

JavaScript SDK trace propagation not available via CDN

Trace propagation is not available through the CDN (UMD) build because there is no way to load the tracing runtime from a script tag.

JavaScript SDK enable trace propagation with tracePropagation option

Pass tracePropagation: true when creating the Supabase client to enable trace propagation. This requires loading the tracing runtime first on version 2.112.0 and later with import '@supabase/supabase-js/tracing'

JavaScript SDK trace propagation configuration options

The tracePropagation option accepts either a boolean (true/false) or an object. The object has two properties: enabled (boolean, default false) to enable trace propagation, and respectSamplingDecision (boolean, default true) to control whether non-sampled requests send only traceparent with the sampled flag preserved while omitting tracestate and baggage (true), or always send the full trace context regardless of sampling (false). On versions before 2.112.3, respectSamplingDecision: true skipped all trace headers for non-sampled requests.

JavaScript SDK trace header restriction to Supabase domains

For security, trace headers are only attached to requests targeting Supabase domains (*.supabase.co, *.supabase.in, and localhost for local development). Third-party hosts called through a custom fetch are never tagged with trace headers.

JavaScript SDK Edge Functions CORS configuration for trace headers

Calling Edge Functions from the browser with trace propagation enabled requires the function's CORS allow-list to include the trace headers. In the function, import corsHeaders from npm:@supabase/supabase-js@^2.112.3/cors or add traceparent, tracestate, and baggage to your own allow-list, then redeploy the function.

Sentry Node.js trace propagation configuration

For Sentry on Node.js (including Next.js server-side), set propagateTraceparent: true in Sentry.init() to enable trace propagation with tracePropagation. Sentry's propagator omits traceparent by default.

Sentry browser trace propagation configuration

For Sentry browser SDK, set propagateTraceparent: true and add your project URL (https://<ref>.supabase.co) to tracePropagationTargets in the configuration. Sentry's browser SDK only attaches headers cross-origin for listed targets. For Edge Functions, also add sentry-trace to the function's CORS allow-list because Sentry always sends its own header, which isn't part of corsHeaders.

Datadog dd-trace Node.js trace propagation

Datadog dd-trace for Node.js works with trace propagation out of the box with no additional configuration required. dd-trace injects W3C headers at the HTTP layer itself, even without tracePropagation enabled.

Datadog Browser RUM trace propagation configuration

For Datadog Browser RUM, add your project URL to allowedTracingUrls with the tracecontext propagator type to enable trace propagation.

JavaScript SDK trace propagation warning for missing traceparent

From version 2.112.3 and later, if a propagator is active but doesn't emit traceparent, the SDK logs a one-time console warning naming the headers the propagator wrote.

JavaScript SDK troubleshooting trace propagation - tracing runtime not loaded

On @supabase/supabase-js version 2.112.0 and later, if tracePropagation is enabled but the entry point never imports @supabase/supabase-js/tracing, the SDK logs a one-time console warning and sends requests without trace headers. Check the console for this warning if trace_id is missing from Supabase logs.

JavaScript SDK troubleshooting trace propagation - no active span

The SDK reads the current context when a request is made. If supabase.from(...) is called outside tracer.startActiveSpan(...) or equivalent, there's nothing to propagate. Wrap the call in a span or use OpenTelemetry's automatic instrumentation.

JavaScript SDK troubleshooting trace propagation - missing @opentelemetry/api

@opentelemetry/api must be installed in the app making the request. On @supabase/supabase-js 2.112.0 and later, the tracing subpath imports it directly, so a missing package surfaces as a module resolution error. On versions 2.106.0–2.111.x it's loaded dynamically and the SDK silently no-ops.

JavaScript SDK troubleshooting trace propagation - no TracerProvider registered

@opentelemetry/api defaults to a noop provider that produces non-recorded spans. Ensure the app calls provider.register() or the vendor SDK's equivalent before making requests.

JavaScript SDK troubleshooting trace propagation - sampling decision on old versions

On @supabase/supabase-js versions before 2.112.3, if the upstream trace is not sampled, all trace headers are skipped. From version 2.112.3, non-sampled requests still carry traceparent so log correlation keeps working by default. Set respectSamplingDecision: false to always send the full trace context.

Swift SDK trace propagation requirement

supabase-swift version 2.51.0 or later with swift-tools-version 6.1 or later (for SwiftPM trait support) is required for trace propagation.

Swift SDK enable trace propagation with OpenTelemetry trait

Add the OpenTelemetry trait to the supabase-swift dependency declaration in Package.swift with: .package(url: "https://github.com/supabase/supabase-swift.git", from: "2.51.0", traits: ["OpenTelemetry"]). No changes to SupabaseClient are required. After enabling the trait, the active OpenTelemetry span's trace context is automatically injected as a traceparent header on every outgoing request across PostgREST, Storage, Auth, Functions, and Realtime.

Swift SDK trace propagation span behavior

In the Swift SDK, when there is no active span, the traceparent header is not added to requests. The trace context is only injected when a span is active.

Dart SDK trace propagation requirement

The Dart SDK requires supabase 2.x or later (Flutter or Dart-only) to support trace propagation.

Dart SDK trace propagation configuration with TracePropagationOptions

Pass TracePropagationOptions when creating the SupabaseClient with enabled: true and a traceContextProvider callback that returns the current TraceContext from your tracing library. Return null when there is no active span. For supabase_flutter, pass the same option through Supabase.initialize.

Dart SDK trace propagation configuration options

TracePropagationOptions has three properties: enabled (bool, default false) to enable trace propagation, respectSamplingDecision (bool, default true) to skip propagation if the upstream trace is not sampled or always attach trace_id when false (useful for log correlation even when traces are not exported), and traceContextProvider (TraceContextProvider?, default null) a callback returning the current TraceContext or null when there is no active span.

Dart SDK trace header restriction to Supabase domains

In the Dart SDK, trace headers are only injected on requests targeting Supabase hosts (*.supabase.co, *.supabase.in, your project host, and loopback addresses for local development). Third-party hosts never receive trace headers.

Python SDK trace propagation via opentelemetry-instrumentation-httpx

The Python SDK's OpenTelemetry propagation is handled entirely through the opentelemetry-instrumentation-httpx package. Install opentelemetry-sdk and opentelemetry-instrumentation-httpx, then instrument the httpx client using HTTPXClientInstrumentor().instrument(). This instruments all httpx clients in the process. Optionally use HTTPXClientInstrumentor.instrument_client to instrument only the Supabase client in the specific sub-package.

Python SDK trace propagation automatic span propagation

In the Python SDK, after setting up the TracerProvider and instrumenting the httpx client, any active span is propagated automatically. Create the SupabaseClient as normal and use tracer.start_as_current_span to wrap queries.

Supabase logs contain trace_id from trace propagation

After trace context is flowing through, the trace_id appears in API Gateway logs (every request to PostgREST, Auth, Storage, and Realtime) and Edge Function logs (invocations and any structured logs emitted from within the function).

Correlating Supabase logs with client and server traces using trace_id

If Supabase logs are forwarded to a third-party backend via Log Drains, you can join Supabase logs to your own client and server traces using the shared trace_id. This is especially useful for self-hosted setups where you already operate your own OpenTelemetry collector, making Supabase logs first-class citizens in your existing tracing UI.

Give your agent this brain