{"record":{"id":"6a8910b4eb5aa75b","repo":"zitadel/zitadel","slug":"unable-to-read-steps-w","errorCode":null,"errorMessage":"unable to read steps: %w","messagePattern":"unable to read steps: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/setup/config.go","lineNumber":230,"sourceCode":"\t\tv.SetConfigFile(file)\n\t\terr := v.MergeInConfig()\n\t\tlogging.OnError(ctx, err).Warn(\"unable to read setup file\", \"file\", file)\n\t}\n\n\tsteps := new(Steps)\n\terr = v.Unmarshal(steps,\n\t\tviper.DecodeHook(mapstructure.ComposeDecodeHookFunc(\n\t\t\thook.Base64ToBytesHookFunc(),\n\t\t\thook.TagToLanguageHookFunc(),\n\t\t\thook.StringToURLHookFunc(),\n\t\t\tmapstructure.StringToTimeDurationHookFunc(),\n\t\t\tmapstructure.StringToTimeHookFunc(time.RFC3339),\n\t\t\tmapstructure.StringToSliceHookFunc(\",\"),\n\t\t\tmapstructure.TextUnmarshallerHookFunc(),\n\t\t)),\n\t)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to read steps: %w\", err)\n\t}\n\treturn steps, nil\n}\n","sourceCodeStart":212,"sourceCodeEnd":234,"githubUrl":"https://github.com/zitadel/zitadel/blob/13948f2bcd6f257794dbd6d342c2ac30bc88fe54/cmd/setup/config.go#L212-L234","documentation":"This error wraps a failure from the mapstructure/viper decoding step in cmd/setup/config.go's readSteps, which unmarshals the YAML config's Steps section into the migration Steps struct. ZITADEL throws it when the setup steps configuration cannot be decoded into the strongly-typed steps object. It indicates the setup command's config for migration steps is malformed or has incompatible types.","triggerScenarios":"Running `zitadel setup` (or start with steps config) when config.ReadConfig/decoder fails: a YAML key in the Steps section has the wrong type (e.g. string where int expected), an unsupported TextUnmarshaller target value, or the underlying config read returns an error.","commonSituations":"Hand-edited defaults.yaml/config.yaml with a typo in a steps field type; passing --steps or step config via env vars with values that fail mapstructure hooks (invalid RFC3339 timestamps, wrong comma-separated list); upgrading ZITADEL and an old steps key no longer matches the struct.","solutions":["Check the wrapped error (%w) for the exact mapstructure field that failed to decode.","Fix the type of the offending field in your config YAML / env override to match the Steps struct in cmd/setup/config.go.","Ensure timestamp-like step fields use valid RFC3339 values and list fields are comma-separated strings.","If running an upgraded version, remove stale step keys from your custom config and rely on defaults."],"exampleFix":"// before (config.yaml)\nSteps:\n  FirstInstancePat: 12345   # wrong type: string expected\n// after\nSteps:\n  FirstInstancePat: \"pat12345\"","handlingStrategy":"validation","validationCode":"// Validate steps config fields' types before running setup:\n// e.g. ensure string fields are strings and time fields parse as RFC3339\nif _, err := time.Parse(time.RFC3339, cfg.Steps.SomeTimeField); err != nil {\n    return fmt.Errorf(\"invalid Steps.SomeTimeField: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if _, err := readSteps(v); err != nil {\n    var decodeErr *mapstructure.Error\n    if errors.As(err, &decodeErr) { /* inspect failing fields */ }\n    return err\n}","preventionTips":["Keep custom step overrides minimal; rely on defaults.yaml.","Run config through a YAML linter before deployment.","After upgrading ZITADEL, diff your Steps config against the new defaults.yaml."],"tags":["go","config","setup","mapstructure"],"backgroundTag":"config-type-mismatch","analyzedSha":"13948f2bcd6f257794dbd6d342c2ac30bc88fe54","analyzedAt":"2026-09-06T10:16:19.814Z","contentChangedAt":"2026-09-06T10:16:19.814Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}