Can not flush cache

caddy version: 1.11.2

$ curl -v -X PURGE http://localhost:2019/souin-api/souin/flush
* Host localhost:2019 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:2019...
* Connected to localhost (::1) port 2019
* using HTTP/1.x
> PURGE /souin-api/souin/flush HTTP/1.1
> Host: localhost:2019
> User-Agent: curl/8.14.1
> Accept: */*
> 
* Request completely sent off
* Empty reply from server
* shutting down connection #0
curl: (52) Empty reply from server

log

{"level":"info","ts":1773995888.740839,"logger":"admin.api","msg":"received request","method":"PURGE","host":"localhost:2019","uri":"/souin-api/souin/flush","remote_ip":"10.88.0.112","remote_port":"54338","headers":{"Accept":["*/*"],"User-Agent":["curl/8.14.1"]}}
{"level":"info","ts":1773995888.7425144,"msg":"http: panic serving 10.88.0.112:54338: runtime error: invalid memory address or nil pointer dereference\ngoroutine 2663 [running]:\nnet/http.(*conn).serve.func1()\n\tnet/http/server.go:1907 +0xbd\npanic({0x1c7bd00?, 0x37542c0?})\n\truntime/panic.go:860 +0x13a\ngithub.com/darkweak/souin/pkg/api.(*SouinAPI).HandleRequest(0x2514e81b5020, {0x23581f0, 0x2514e9083110}, 0x2514e8130140)\n\tgithub.com/darkweak/souin@v1.7.7/pkg/api/souin.go:316 +0x931\ngithub.com/caddyserver/cache-handler.(*adminAPI).handleAPIEndpoints(0x2514e8643050?, {0x23581f0, 0x2514e9083110}, 0x2514e8130140)\n\tgithub.com/caddyserver/cache-handler@v0.16.0/admin.go:41 +0xf2\ngithub.com/caddyserver/caddy/v2.AdminHandlerFunc.ServeHTTP(0x425234?, {0x23581f0?, 0x2514e9083110?}, 0x2514e925aab0?)\n\tgithub.com/caddyserver/caddy/v2@v2.11.2/admin.go:1360 +0x29\ngithub.com/caddyserver/caddy/v2.(*AdminConfig).newAdminHandler.(*AdminConfig).newAdminHandler.func2.func6({0x23581f0, 0x2514e9083110}, 0x2514e8130140)\n\tgithub.com/caddyserver/caddy/v2@v2.11.2/admin.go:248 +0x7b\nnet/http.HandlerFunc.ServeHTTP(0x2358580?, {0x23581f0?, 0x2514e9083110?}, 0x2514e860b750?)\n\tnet/http/server.go:2286 +0x29\ngithub.com/caddyserver/caddy/v2.(*AdminConfig).newAdminHandler.func1.instrumentHandlerCounter.1({0x2358580?, 0x2514e82fe5a0?}, 0x2514e8130140)\n\tgithub.com/caddyserver/caddy/v2@v2.11.2/metrics.go:56 +0x6f\nnet/http.HandlerFunc.ServeHTTP(0x2514e927e3c0?, {0x2358580?, 0x2514e82fe5a0?}, 0x74c47f?)\n\tnet/http/server.go:2286 +0x29\nnet/http.(*ServeMux).ServeHTTP(0x2514e8640f90?, {0x2358580, 0x2514e82fe5a0}, 0x2514e8130140)\n\tnet/http/server.go:2828 +0x1c7\ngithub.com/caddyserver/caddy/v2.adminHandler.serveHTTP({0x2514e927e3c0, 0x0, 0x0, {0x2514e7e86528, 0x1, 0x1}, 0x0}, {0x2358580, 0x2514e82fe5a0}, 0x2514e8130140)\n\tgithub.com/caddyserver/caddy/v2@v2.11.2/admin.go:891 +0x793\ngithub.com/caddyserver/caddy/v2.adminHandler.ServeHTTP({0x2514e927e3c0, 0x0, 0x0, {0x2514e7e86528, 0x1, 0x1}, 0x0}, {0x2358580, 0x2514e82fe5a0}, 0x2514e8130140)\n\tgithub.com/caddyserver/caddy/v2@v2.11.2/admin.go:816 +0x7a5\nnet/http.serverHandler.ServeHTTP({0x2514e829d180?}, {0x2358580?, 0x2514e82fe5a0?}, 0x1?)\n\tnet/http/server.go:3311 +0x8e\nnet/http.(*conn).serve(0x2514e925aa20, {0x235da70, 0x2514e85e1380})\n\tnet/http/server.go:2073 +0x650\ncreated by net/http.(*Server).Serve in goroutine 2372\n\tnet/http/server.go:3464 +0x485"}

Caddyfile

{
	debug
	order cache before rewrite

	cache {
		api {
			souin
		}
	}
}

example.com {
    @cacheable {
        not path /
    }
    handle @cacheable {
        cache {
            ttl 120s
        }
    }

    file_server
}

I dug into this locally and was able to reproduce, patch, and verify it.

Environment:

FrankenPHP/Caddy: v2.11.2
cache-handler: v0.16.0
Souin: v1.7.8

Repro:

Warm a tagged page so it returns Surrogate-Key: post:2
Confirm it is cached (Cache-Status: Souin; hit)
Call:
PURGE http://localhost:2019/souin-api/souin
Surrogate-Key: post:2

Before patch:

GET /souin-api/souin works
PURGE /souin-api/souin panics in github.com/darkweak/souin/pkg/api/souin.go:330
nil deref is on s.surrogateStorage.Purge(r.Header)

Root cause:

this is on the admin API path, not the frontend route path
admin.go builds the Souin handler map before the live surrogate storage exists
the live surrogate storage is created later by the HTTP cache middleware in httpcache.go
so the admin handler map ends up holding a nil surrogateStorage, while normal frontend caching still works

In other words: initialization order is wrong for the admin purge API.

I got it working with a small refactor:

move runtime surrogate lookup behind SouinApp
let admin handlers build against the live surrogate storage at request time
keep a nil-safe guard around the middleware’s LoadOrStore result

Patch fragment:

diff --git a/app.go b/app.go
index ... .. ...
--- a/app.go
+++ b/app.go
@@
 func (s SouinApp) Provision(_ caddy.Context) error {
 	return nil
 }
+
+func (s *SouinApp) getSurrogateStorage() providers.SurrogateInterface {
+	if s.SurrogateStorage != nil {
+		return s.SurrogateStorage
+	}
+
+	up.Range(func(key, value any) bool {
+		if key != surrogate_key || value == nil {
+			return true
+		}
+
+		storage, ok := value.(providers.SurrogateInterface)
+		if !ok {
+			return true
+		}
+
+		s.SurrogateStorage = storage
+		return false
+	})
+
+	return s.SurrogateStorage
+}
diff --git a/admin.go b/admin.go
index ... .. ...
--- a/admin.go
+++ b/admin.go
@@
 func (a *adminAPI) regenerateHandlerMap() {
 	config := Configuration{
 		API: a.app.API,
 		DefaultCache: DefaultCache{
 			TTL: configurationtypes.Duration{
 				Duration: 120 * time.Second,
 			},
 		},
 	}
 
-	a.InternalEndpointHandlers = api.GenerateHandlerMap(&config, a.app.Storers, a.app.SurrogateStorage)
+	a.InternalEndpointHandlers = api.GenerateHandlerMap(&config, a.app.Storers, a.app.getSurrogateStorage())
 }
diff --git a/httpcache.go b/httpcache.go
index ... .. ...
--- a/httpcache.go
+++ b/httpcache.go
@@
 	bh := middleware.NewHTTPCacheHandler(&s.Configuration)
 	surrogates, ok := up.LoadOrStore(surrogate_key, bh.SurrogateKeyStorer)
-	if ok {
+	if ok && surrogates != nil {
 		bh.SurrogateKeyStorer = surrogates.(surrogates_providers.SurrogateInterface)
 	}

Also related: https://caddy.community/t/caddyserver-cache-handler-doesnt-purge-by-surrogate-key/30857/5

@darkweak

Any hints? @darkweak

Hey, as far as I know, the Provision function initialize the map asynchronously. That's why sometimes it may panic, because it's in a weird state.

darkweak/souin#732

Navigation Menu

Repository navigation

Can not flush cache #140

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Can not flush cache #140

Description

Activity

kasparsd commented on Mar 29, 2026

sylloger commented on Apr 4, 2026

darkweak commented on Apr 8, 2026

janus-reith commented on May 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions