caddyserver/caddy · error

getting events app: %v

Error message

getting events app: %v

What it means

After loading the tls app, the http app loads the events app via ctx.App("events"); any failure provisioning the events app (bad subscriptions, invalid event handler modules) is wrapped as 'getting events app'. The http app depends on events for its event hooks.

Source

Thrown at modules/caddyhttp/app.go:202

	}
}

// Provision sets up the app.
func (app *App) Provision(ctx caddy.Context) error {
	// store some references
	app.logger = ctx.Logger()
	app.ctx = ctx

	// provision TLS and events apps
	tlsAppIface, err := ctx.App("tls")
	if err != nil {
		return fmt.Errorf("getting tls app: %v", err)
	}
	app.tlsApp = tlsAppIface.(*caddytls.TLS)

	eventsAppIface, err := ctx.App("events")
	if err != nil {
		return fmt.Errorf("getting events app: %v", err)
	}

	repl := caddy.NewReplacer()

	// this provisions the matchers for each route,
	// and prepares auto HTTP->HTTPS redirects, and
	// is required before we provision each server
	err = app.automaticHTTPSPhase1(ctx, repl)
	if err != nil {
		return err
	}

	if app.Metrics != nil {
		app.Metrics.init = sync.Once{}
		app.Metrics.httpMetrics = &httpMetrics{}
		// Scan config for allowed hosts to prevent cardinality explosion
		app.Metrics.scanConfigForHosts(app)
		if err := app.Metrics.provisionOTLP(ctx); err != nil {

View on GitHub (pinned to 50e54ee279)

Solutions

1. Read the nested error after the colon — it identifies the events-side failure.
2. Fix the events subscription/handler config (see errors 313/314 remedies).
3. Remove or comment out the events block to confirm the rest of the config starts.
4. Validate the whole config with 'caddy validate' to get the direct error.

Example fix

// before (caddyfile)
{
    events {
        on http server_shutdown {
            handler nope
        }
    }
}

// after
{
    events {
        on http server_shutdown {
            handler exec {
                command /usr/bin/logger shutdown
            }
        }
    }
}

if err := caddy.Validate(cfg); err != nil {
    if strings.Contains(err.Error(), "getting events app") {
        // root cause is the nested events error — fix the events block, not http
    }
    return err
}

When it happens

Trigger: A config with an invalid events app section (bad handler module, empty handlers, malformed subscription) loaded indirectly while the http app provisions.

Common situations: Same root causes as caddyevents errors 313/314, but surfacing through the http app; typical when the events block was added for webhooks/exec handlers and the plugin is missing or misconfigured.

Related errors

• getting tls app: %v
• loading %s app module: %v
• loading event subscriber modules: %v
• server %s: %v
• server %s: setting up route handlers: %v

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/5f711a32b24eae61. Report an issue: GitHub.