Debugging

Useful entry points when something is wrong in a local or installed Argo CD.

Logs

All components use logrus (configured by util/log/) and respect two flags:

• --loglevel debug|info|warn|error
• --logformat json|text

Both are exposed at the binary level (see cmd/argocd-server/commands/argocd_server.go and similar) and at the CLI level (cmd/argocd/commands/root.go registers --logformat/--loglevel as persistent flags).

In a Procfile dev environment (goreman start), the components emit colorized text logs (FORCE_LOG_COLORS=1).

Profiling

util/profile/ exposes pprof endpoints on the metrics port of each component. With the dev Procfile defaults (metrics port is component-specific), you can:

go tool pprof http://localhost:<metrics-port>/debug/pprof/profile?seconds=30

For runtime stats, util/stats/ and the argoproj/pkg/v2/stats library record GC and mem stats. The application controller logs aggregated stats periodically.

Tracing

OpenTelemetry tracing is wired in via util/trace/. Enable it by setting --otlp-address (and optionally --otlp-headers) on each binary. The Procfile passes ${ARGOCD_OTLP_ADDRESS} so you can point a local collector at all components in one shot.

Common error patterns

Symptom	First thing to check	Where the code lives
App stuck OutOfSync after push	Repo server cache; verify argocd-repo-server got the webhook	util/webhook/webhook.go, reposerver/repository/repository.go
Permission denied in CLI/UI	Casbin RBAC policy in argocd-rbac-cm	util/rbac/rbac.go, server/rbacpolicy/
manifests-too-large install error	Use kubectl apply --server-side --force-conflicts	manifests/install.yaml
Sync fails on hooks	Inspect hook resources and their phases	controller/hook.go, controller/sync.go
ApplicationSet not generating	Generator validation errors in controller logs	applicationset/controllers/applicationset_controller.go, applicationset/generators/
Notifications silent	Trigger templates / subscriptions config	notification_controller/, notifications_catalog/, util/notification/
OIDC redirect loop	argocd-cm oidc.config, Dex pod logs	util/oidc/oidc.go, cmd/argocd-dex/commands/
Helm/Kustomize render fails	Repo server logs, run argocd app manifests <app>	util/helm/, util/kustomize/

Reproducing controller behavior

controller/appcontroller.go is the primary loop and very dense. To reproduce its behavior locally:

1. Bring up the dev stack (goreman start).
2. Apply a fake Application CR pointing at a local git repo (provided by test/fixture/testrepos/start-git.sh).
3. Watch logs in controller's console; bump --loglevel debug if needed.
4. Inspect the cached state in Redis (redis-cli -p 6379 KEYS "*").

Inspecting the gRPC API directly

argocd itself talks gRPC to argocd-server. For raw debugging, use grpcurl:

grpcurl -plaintext localhost:8080 list
grpcurl -plaintext -H "Authorization: Bearer $TOKEN" \
        localhost:8080 application.ApplicationService/List

The proto definitions are under pkg/apiclient/, server/application/application.proto, and server/repository/repository.proto.

When all else fails

• The bug_triage.md document under docs/ lists how the maintainers triage incoming bugs and what good repro reports look like.
• SECURITY.md and SECURITY_CONTACTS describe responsible disclosure for security issues.