Pitfalls and danger zones

Areas that look innocent but are easy to break. If you're working in any of these, slow down.

Wire DI graph

pkg/server/wire.go is small to read but the implications are global. Reordering or removing a service can break startup with a cryptic error from generated code far from the change. Always run make gen-go and a full make test-go-unit after touching it.

Database migrations

Migrations in pkg/services/sqlstore/migrations/ are forward-only and run on every server startup. Mistakes ship to every existing user the moment they upgrade.

• Don't ALTER COLUMN. Add a new column, copy, drop the old.
• Test on all three databases (SQLite, MySQL, Postgres) — make test-go-integration-postgres, -mysql.
• For data backfills, batch and make idempotent so partial failures can be retried.
• Never delete a migration after it's shipped. Add a no-op or new one to "fix" the previous one.

Dashboard schema (v1 ↔ v2)

The conversion code in apps/dashboard/pkg/migration/conversion/ has to be lossless in both directions for arbitrary nested layouts. A bug here corrupts user dashboards on save. Changes here need a thorough test pass against the entire fixture set in apps/dashboard/pkg/migration/.

Frontend yarn test defaults to --watch

Running yarn test path/to/file will block the terminal until you Ctrl-C. Always pass --watchAll=false (or use yarn jest --no-watch) in scripts and AI-driven workflows.

pkg/api/ test compilation is slow

The pkg/api/ package has a heavy import graph; compiling its tests can take ~2 minutes on first run. Use -run TestName to filter to a specific test rather than running the whole package iteratively.

Feature toggle drift

When you edit pkg/services/featuremgmt/registry.go, you must run make gen-feature-toggles and commit the regenerated toggles_gen.* files plus packages/grafana-data/src/types/featureToggles.gen.ts. CI will fail otherwise; the diff is just clutter at that point.

Plugin signing

Plugin signature verification can reject a plugin that worked yesterday if its manifest changes. When debugging plugin load failures, the pkg/plugins/manifestverifier/ error messages are usually the right place to look.

make run debug build is huge

The dev build uses -gcflags all=-N -l for debugger-friendly output. The resulting binary is many times larger than a release build. Don't be surprised by the size of bin/<arch>/grafana after make run.

Permissions vs not-found

Many endpoints intentionally return 404 instead of 403 when the user lacks permission to read a resource — to avoid leaking the existence of resources outside the user's scope. When debugging, check the access-control filter (pkg/services/accesscontrol/filter.go) before assuming the resource is genuinely missing.

Centrifuge HA needs Redis

Without Redis, Live channels are local to a single Grafana node — clients connected to different replicas won't see each other's events. Configure [live] ha_engine = redis for multi-node deployments.

Generated files

Files like wire_gen.go, toggles_gen.*, zz_generated*.go, *_spec_gen.go, featureToggles.gen.ts, panelcfg_types.gen.ts, etc. are not edited by hand. CI will fail if a make gen-* target isn't re-run. When in doubt, rerun all make gen-* after a refactor and check the diff.

Concurrent dashboard saves

Dashboards have an optimistic-concurrency version field. The save handler returns 412 (Precondition Failed) if the version on disk is newer. The frontend handles this — but custom integrations need to follow the same pattern or risk silent overwrites.

Long-running migrations on startup

When a server starts up against a database with pending migrations, requests block until migrations finish. For very large databases, this can take minutes. Health checks (/api/health) return 503 until migrations complete.

Build tags

Files behind build tags enterprise and pro aren't visible in the OSS source tree but are referenced by interfaces. If a function signature changes in OSS code that has an enterprise counterpart, the enterprise build can break in a separate repository — the CI for that lives elsewhere and you may not see the failure until later.