{"record":{"id":"b4f80c4e4f103801","repo":"hashicorp/nomad","slug":"failed-to-retrieve-config-schema-for-internal-plug","errorCode":null,"errorMessage":"failed to retrieve config schema for internal plugin %s: %v","messagePattern":"failed to retrieve config schema for internal plugin (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"helper/pluginutils/loader/init.go","lineNumber":154,"sourceCode":"\t\t}\n\t\tinfo.version = v\n\n\t\t// Detect the plugin API version to use\n\t\tav, err := l.selectApiVersion(i)\n\t\tif err != nil {\n\t\t\t_ = multierror.Append(&mErr, fmt.Errorf(\"failed to validate API versions %v for internal plugin %s: %v\", i.PluginApiVersions, k, err))\n\t\t\tcontinue\n\t\t}\n\t\tif av == \"\" {\n\t\t\tl.logger.Warn(\"skipping plugin because supported API versions for plugin and Nomad do not overlap\", \"plugin\", k)\n\t\t\tcontinue\n\t\t}\n\t\tinfo.apiVersion = av\n\n\t\t// Get the config schema\n\t\tschema, err := base.ConfigSchema()\n\t\tif err != nil {\n\t\t\t_ = multierror.Append(&mErr, fmt.Errorf(\"failed to retrieve config schema for internal plugin %s: %v\", k, err))\n\t\t\tcontinue\n\t\t}\n\t\tinfo.configSchema = schema\n\n\t\t// Store the fingerprinted config\n\t\tfingerprinted[k] = info\n\t}\n\n\tif err := mErr.ErrorOrNil(); err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn fingerprinted, nil\n}\n\n// selectApiVersion takes in PluginInfo and returns the highest compatable\n// version or an error if the plugins response is malformed. If there is no\n// overlap, an empty string is returned.","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/helper/pluginutils/loader/init.go#L136-L172","documentation":"After selecting the API version, initInternal asks the plugin for its configuration schema via base.ConfigSchema(). If the plugin returns an error, this message is appended to the multierror and the plugin is skipped, since the loader cannot validate the plugin's config without a schema.","triggerScenarios":"initInternal calls base.ConfigSchema() on the fingerprinted internal plugin and it errors — typically a plugin whose schema method is unimplemented for the negotiated API version or returns an error derived from internal state.","commonSituations":"Custom internal plugin implements ConfigSchema incorrectly or not at all; negotiated API version lacks a schema implementation; plugin misconfigured such that schema generation depends on failing state.","solutions":["Implement ConfigSchema in the plugin's base so it returns a valid hclspec.Schema for the negotiated API version","Check the wrapped %v error for the root cause returned by the plugin","Downgrade/upgrade so a supported API version is negotiated for which the plugin implements ConfigSchema"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"schema, err := p.ConfigSchema()\nif err != nil || schema == nil {\n    return fmt.Errorf(\"plugin must return a non-nil config schema\")\n}","typeGuard":null,"tryCatchPattern":"if err := loader.Init(...); err != nil {\n    if strings.Contains(err.Error(), \"failed to retrieve config schema\") {\n        // plugin's ConfigSchema failed; check the inner error for the cause\n    }\n}","preventionTips":["Implement ConfigSchema for every supported API version","Return a static hclspec schema rather than one derived from mutable state","Cover ConfigSchema in the plugin's unit tests"],"tags":["go","plugin-loader","config-schema","nomad"],"backgroundTag":"plugin-config-schema-error","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}