thanos-io/thanos · error

iter

Error message

iter

What it means

In the bucket `ls` command, after fetching metadata for every object, the code iterates over the metas and calls printBlock(meta) for each; any error from that callback (which is itself the 'execute template' wrap of tmpl.Execute) is re-wrapped as 'iter'. So this error means the per-object printing step failed while iterating, almost always due to a bad --format template.

Solutions

1. Fix the --format template so it only references fields present on metadata.Meta.
2. Add {{if}} nil-guards around optional pointer fields in the template.
3. If the wrapped inner error mentions a field, compare against the metadata.Meta struct definition and correct it.
4. Test the template against a single block ID before running on the whole bucket.

Example fix

// before
thanos tools bucket ls bkt --format '{{.MinTime }}'
// after
thanos tools bucket ls bkt --format '{{.MinTime}}'  // ensure field exists on metadata.Meta; otherwise use .MinMaxTime as defined

if _, err := template.New("").Parse(format); err != nil {
    return fmt.Errorf("invalid --format: %w", err)
}

err := runLs(...)
if err != nil && strings.Contains(err.Error(), "iter") {
    // retry with the default template
    return runLsWithFormat("{{.ULID}}")
}

When it happens

Trigger: Running `thanos tools bucket ls <bucket> --format '<template>'` where the template fails to execute against one of the listed metadata.Meta values (nonexistent field, nil pointer dereference in template) — cmd/thanos/tools_bucket.go:524.

Common situations: Same as the template execution failure: templates copied from docs for a different struct, fields renamed after Thanos upgrades, or accessing .Thana on blocks whose meta lacks it.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• execute template
• level is bigger then default set of
• unknown sync strategy
• get compaction levels
• penalty based deduplication needs at least one replica…

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/d2d50053cbbb5b58. Report an issue: GitHub.

Appendix: source

Thrown at cmd/thanos/tools_bucket.go:524

			}
			printBlock = func(m *metadata.Meta) error {
				if err := tmpl.Execute(os.Stdout, &m); err != nil {
					return errors.Wrap(err, "execute template")
				}
				fmt.Fprintln(os.Stdout, "")
				return nil
			}
		}

		metas, _, err := fetcher.Fetch(ctx)
		if err != nil {
			return err
		}

		for _, meta := range metas {
			objects++
			if err := printBlock(meta); err != nil {
				return errors.Wrap(err, "iter")
			}
		}
		level.Info(logger).Log("msg", "ls done", "objects", objects)
		return nil
	})
}

func registerBucketInspect(app extkingpin.AppClause, objStoreConfig *extflag.PathOrContent) {
	cmd := app.Command("inspect", "Inspect all blocks in the bucket in detailed, table-like way.")

	tbc := &bucketInspectConfig{}
	tbc.registerBucketInspectFlag(cmd)

	output := cmd.Flag("output", "Output format for result. Currently supports table, csv, tsv.").Default("table").Enum(outputTypes...)

	cmd.Setup(func(g *run.Group, logger log.Logger, reg *prometheus.Registry, _ opentracing.Tracer, _ <-chan struct{}, _ bool) error {

		// Parse selector.

View on GitHub (pinned to 35b8b99117)