{"id":"0e5afcde16122853","repo":"guzzle/guzzle","slug":"middleware-not-found-s","errorCode":null,"errorMessage":"Middleware not found: %s","messagePattern":"Middleware not found: (.+?)","errorType":"validation","errorClass":"\\InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/HandlerStack.php","lineNumber":246,"sourceCode":"\n    public function __unserialize(array $data): void\n    {\n        $this->handler = null;\n        $this->stack = [];\n        $this->cached = null;\n\n        throw new \\LogicException(static::class.' should never be unserialized');\n    }\n\n    private function findByName(string $name): int\n    {\n        foreach ($this->stack as $k => $v) {\n            if ($v[1] === $name) {\n                return $k;\n            }\n        }\n\n        throw new \\InvalidArgumentException(\\sprintf('Middleware not found: %s', DiagnosticValue::escape($name)));\n    }\n\n    /**\n     * Splices a function into the middleware list at a specific position.\n     *\n     * @param callable(callable&THandler): (callable&THandler) $middleware\n     */\n    private function splice(string $findName, string $withName, callable $middleware, bool $before): void\n    {\n        $this->cached = null;\n        $idx = $this->findByName($findName);\n        $tuple = [$middleware, $withName];\n\n        if ($before) {\n            if ($idx === 0) {\n                \\array_unshift($this->stack, $tuple);\n            } else {\n                $replacement = [$tuple, $this->stack[$idx]];","sourceCodeStart":228,"sourceCodeEnd":264,"githubUrl":"https://github.com/guzzle/guzzle/blob/9b200fc5805036b331d6031199880dadecae0275/src/HandlerStack.php#L228-L264","documentation":"before() and after() splice a middleware next to an existing named middleware via findByName(), which scans $stack for a tuple whose name (second element) matches. If no pushed/unshifted middleware was registered with that exact name, it throws InvalidArgumentException with the escaped name.","triggerScenarios":"Calling $stack->before('cookies', $mw) or $stack->after('http_errors', $mw) when no middleware named 'cookies'/'http_errors' exists; typo in the name; calling before/after on a stack built with new HandlerStack() that never received HandlerStack::create()'s defaults.","commonSituations":"Registering a custom stack and assuming default names exist; name case mismatch; ordering before()/after() before the target middleware has been pushed.","solutions":["Ensure the target middleware is pushed with the exact name first: $stack->push(Middleware::cookies(), 'cookies').","Check the name spelling and case against the second argument used at push time.","For the default stack, use HandlerStack::create() which registers http_errors, allow_redirects, auth, cookies, prepare_body."],"exampleFix":"// before\n$stack = new HandlerStack(new CurlHandler());\n$stack->before('cookies', $myMiddleware); // throws: \"Middleware not found: cookies\"\n\n// after\n$stack = HandlerStack::create();          // registers default named middlewares\n$stack->before('cookies', $myMiddleware); // now succeeds","handlingStrategy":"validation","validationCode":"// Guard before()/after() by checking the name exists:\n$has = false;\nforeach ($stack as $tuple) {\n    if (($tuple[1] ?? null) === $findName) { $has = true; break; }\n}\nif (! $has) {\n    throw new \\InvalidArgumentException(\"Unknown middleware: $findName\");\n}\n$stack->before($findName, $mw);","typeGuard":null,"tryCatchPattern":"try {\n    $stack->before($findName, $mw);\n} catch (\\InvalidArgumentException $e) {\n    // Either push the target middleware first, or append instead\n    $stack->push($mw);\n}","preventionTips":["Use HandlerStack::create() to get the well-known default names (http_errors, allow_redirects, auth, cookies, prepare_body).","Keep an enum/list of middleware names you have registered and reference it for before/after.","Prefer push() with explicit names over fragile relative ordering when possible."],"tags":["handlerstack","middleware","configuration","ordering"],"analyzedSha":"9b200fc5805036b331d6031199880dadecae0275","analyzedAt":"2026-08-04T21:24:26.648Z","schemaVersion":2}