Connect Astro to Bugsink

Astro can run application code in the browser and on the server. Bugsink can capture errors from both sides, keep the request that reached a failed server route, and use production source maps to show the original source.

This guide connects both Astro runtimes, triggers a deliberate browser error and server API error, and uploads the source maps for the production build. To follow along, create a Bugsink project and copy its DSN. The quickstart guide shows where to find it.

Install the Astro SDK

Install the open-source Sentry SDK for Astro. Bugsink accepts the SDK’s event protocol, so it can send errors directly to your Bugsink project:

npm install @sentry/astro

Add the Astro integration

Add sentry() to the integrations in astro.config.mjs. Keep your existing output mode and adapter; this example uses Astro’s Node adapter for a server-rendered application:

import node from "@astrojs/node";
import sentry from "@sentry/astro";
import { defineConfig } from "astro/config";


export default defineConfig({
  output: "server",
  adapter: node({ mode: "standalone" }),
  integrations: [
    sentry({
      release: {
        name: "",
        create: false,
        inject: false,
      },
      sourcemaps: {
        upload: false,
        delete: false,
      },
      telemetry: false,
    }),
  ],
  vite: {
    build: {
      assetsInlineLimit: 0,
      sourcemap: "hidden",
    },
  },
});

The integration adds Astro’s error middleware and prepares browser and server bundles for source mapping. Release management and automatic upload are turned off here because Bugsink uses debug-ID source maps and a separate, reliable upload step below. assetsInlineLimit: 0 keeps small page scripts as files so their bundles and maps can be uploaded together.

Initialize the browser SDK

Create sentry.client.config.ts in the project root. Astro loads it before your page scripts, allowing the SDK to report uncaught errors and unhandled promise rejections from the browser:

import * as Sentry from "@sentry/astro";


Sentry.init({
  dsn: import.meta.env.PUBLIC_SENTRY_DSN,
});

The PUBLIC_ prefix makes the DSN available while Astro builds the browser bundle. A DSN only identifies the destination project; it is expected to be present in browser code.

Initialize the server SDK

Create sentry.server.config.ts beside it. The server reads its DSN from the runtime environment, so it does not need to be built into the server bundle:

import * as Sentry from "@sentry/astro";


Sentry.init({
  dsn: process.env.SENTRY_DSN,
});

Upload the production source maps

Production builds change the browser and server code that actually runs. Uploading their hidden maps lets Bugsink turn minified or bundled frames back into the Astro and TypeScript files you edit.

Build with the project DSN

Supply the public DSN when you create the production build:

PUBLIC_SENTRY_DSN=https://key@bugsink.example/1 npm run build

The maps remain in dist/client and dist/server for the upload step but are not referenced by the JavaScript sent to browsers.

Upload the completed build

Create a project-bound Bugsink token with the debug-files:upload capability. Keep this token in your release environment and out of the browser bundle. Then upload both halves of the build with sentry-cli:

SENTRY_AUTH_TOKEN=your-project-token \
npx --yes @sentry/cli@3.8.2 \
  --url https://bugsink.example \
  sourcemaps --org bugsink --project your-project-slug upload \
  dist/client dist/server

Bugsink has no organization object, so bugsink is only a compatibility value for --org. Upload the maps for every production build before that build can receive traffic.

See a browser error in Bugsink

Start the production server with the server-side DSN:

HOST=127.0.0.1 PORT=3000 \
SENTRY_DSN=https://key@bugsink.example/1 \
npm start

This page calls ordinary inventory code from a click handler. The inventory module raises ProductNotFound when the requested quantity is unavailable:

export class ProductNotFound extends Error {}


export function reserveProduct(sku: string, quantity: number) {
  const available = 0;

  if (quantity > available) {
    throw new ProductNotFound(
      `Cannot reserve ${quantity} unit of ${sku}: only ${available} remain [astro-browser]`,
    );
  }
}

Open http://127.0.0.1:3000/ and click Reserve desk lamp. The browser SDK reports the uncaught error in the background.

See the original browser source

Open the new issue in Bugsink. The uploaded map resolves the production browser bundle to the inventory module and shows the exact line that raised the error.

Bugsink preview

That’s it: browser failures from the production Astro build now reach Bugsink with their original source.

Capture server route errors

Astro’s server middleware also reports exceptions that escape a request. This API route raises ProductNotFound for an unknown product; it does not contain an SDK capture call:

import type { APIRoute } from "astro";


export class ProductNotFound extends Error {}

export const GET: APIRoute = ({ params }) => {
  const products = new Map([["desk-lamp", { name: "Desk lamp", available: 0 }]]);
  const product = params.sku ? products.get(params.sku) : undefined;

  if (!product) {
    throw new ProductNotFound(
      `Product ${params.sku} is not in inventory [astro-server]`,
    );
  }

  return new Response(JSON.stringify(product), {
    headers: { "content-type": "application/json" },
  });
};

Request http://127.0.0.1:3000/api/products/missing. Astro keeps its normal 500 response, while the SDK reports the exception and request to Bugsink.

See the route and request in Bugsink

The server issue shows the parameterized Astro route, concrete request, and original TypeScript throw line after applying the server source map.

Bugsink preview

Server route failures now reach the same Bugsink project with the request and their original source.

Limitations

The @sentry/astro 11.15.0 build integration generates usable maps and injects matching debug IDs, but its automatic uploader currently fails against Bugsink with Invalid URL. Release creation also calls an API that Bugsink does not implement. The build still exits successfully, so its exit status does not prove that maps were uploaded. Keep automatic upload and release management disabled, and use the explicit sentry-cli upload above. The broader build-plugin compatibility gap is tracked in Bugsink issue #109.

This guide uses Astro’s Node adapter in server mode. Static Astro sites have no long-running server runtime, while other adapters can have different startup and request lifecycles; they are not covered by this result.

For handled errors, messages, logging, tags, structured context, and other SDK options, continue with the broader JavaScript guide.

Last tested with Node.js 22.23.4, Astro 7.4.13, @astrojs/node 11.1.14, @sentry/astro 11.15.0, and Bugsink 2.6.4.dev16+g34e47af7a.d20261109 on 20 November 2026.