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/astronpm 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", }, }, });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, });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, });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 buildPUBLIC_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/serverSENTRY_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 startHOST=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]`, ); } }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.
Error
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" }, }); };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.
Error
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.
