{"record":{"id":"251a575a265909ff","repo":"getgrav/grav","slug":"stream-type-could-not-be-initialized","errorCode":null,"errorMessage":"Stream '{$type}' could not be initialized.","messagePattern":"Stream '(.+?)' could not be initialized\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"system/src/Grav/Common/Themes.php","lineNumber":353,"sourceCode":"            if (isset($config['paths'])) {\n                $locator->addPath($scheme, '', $config['paths']);\n            }\n            if (isset($config['prefixes'])) {\n                foreach ($config['prefixes'] as $prefix => $paths) {\n                    $locator->addPath($scheme, $prefix, $paths);\n                }\n            }\n\n            if (in_array($scheme, $registered, true)) {\n                stream_wrapper_unregister($scheme);\n            }\n            $type = !empty($config['type']) ? $config['type'] : 'ReadOnlyStream';\n            if ($type[0] !== '\\\\') {\n                $type = '\\\\RocketTheme\\\\Toolbox\\\\StreamWrapper\\\\' . $type;\n            }\n\n            if (!stream_wrapper_register($scheme, $type)) {\n                throw new InvalidArgumentException(\"Stream '{$type}' could not be initialized.\");\n            }\n        }\n\n        // Load languages after streams has been properly initialized\n        $this->loadLanguages($this->config);\n    }\n\n    /**\n     * Load theme configuration.\n     *\n     * @param string $name   Theme name\n     * @param Config $config Configuration class\n     * @return void\n     */\n    protected function loadConfiguration($name, Config $config)\n    {\n        $themeConfig = CompiledYamlFile::instance(\"themes://{$name}/{$name}\" . YAML_EXT)->content();\n        $config->joinDefaults(\"themes.{$name}\", $themeConfig);","sourceCodeStart":335,"sourceCodeEnd":371,"githubUrl":"https://github.com/getgrav/grav/blob/6040efed04efa69b8209448ed81308e7c24147c2/system/src/Grav/Common/Themes.php#L335-L371","documentation":"During Themes::configure(), every scheme declared in the theme's streams.schemes config (plus the implicit theme scheme) is registered as a PHP stream wrapper after unregistering any existing wrapper with that name. If stream_wrapper_register($scheme, $type) returns false, Grav throws this InvalidArgumentException. $type is resolved to \\RocketTheme\\Toolbox\\StreamWrapper\\<type> unless it starts with a backslash, so both an invalid scheme name and a nonexistent wrapper class land here (PHP emits a warning and returns false when the class does not exist).","triggerScenarios":"A theme's YAML declares streams.schemes.<scheme>.type with a typo (e.g. ReadableStream instead of ReadOnlyStream); a fully-qualified custom type: \\My\\Wrapper whose class is not autoloadable at theme-init time; an invalid scheme name containing ':' or '/' or an empty name; the wrapper class living in a plugin that loads after themes.","commonSituations":"Hand-editing theme YAML to add custom streams; copying stream configuration from a plugin without its autoloader; upgrading rockettheme/toolbox where wrapper classes changed; characters copied from docs into scheme names.","solutions":["Fix the type value in user/themes/<name>/<name>.yaml: use ReadOnlyStream (the default), another class in RocketTheme\\Toolbox\\StreamWrapper, or a leading-backslash FQCN that is already loaded","For custom wrappers, ensure the class exists and is autoloaded before theme init (composer autoload of the theme/plugin providing it)","Keep scheme names simple identifiers (letters, digits, dots, dashes) with no '://' or slashes","Run bin/grav clearcache after fixing so the cached configuration is rebuilt"],"exampleFix":"# before (user/themes/mytheme/mytheme.yaml)\nstreams:\n  schemes:\n    media:\n      type: ReadableStream   # class does not exist\n\n# after\nstreams:\n  schemes:\n    media:\n      type: ReadOnlyStream","handlingStrategy":"validation","validationCode":"// validate custom stream config before Grav registers it\n$class = str_starts_with($type, '\\\\') ? $type : '\\\\RocketTheme\\\\Toolbox\\\\StreamWrapper\\\\' . $type;\nif (!preg_match('/^[a-zA-Z][a-zA-Z0-9.+-]*$/', $scheme) || !class_exists($class)) {\n    throw new InvalidArgumentException(\"Bad stream scheme '{$scheme}' or type '{$type}' — fix theme streams config\");\n}","typeGuard":null,"tryCatchPattern":"try { $themes->configure(); } catch (InvalidArgumentException $e) { // fall back to default stream config and log\n    $grav['debugger']->addException($e); }","preventionTips":["Only declare streams.schemes types that exist in RocketTheme\\Toolbox\\StreamWrapper unless you control autoloading","Lint theme YAML (names, types) in CI before deploy","Re-test custom streams after framework/toolbox upgrades"],"tags":["streams","configuration","theme","filesystem","stream-wrapper"],"backgroundTag":"stream-wrapper-registration-failed","analyzedSha":"6040efed04efa69b8209448ed81308e7c24147c2","analyzedAt":"2026-08-17T05:07:31.593Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}