docker/cli · error

unable to read inspect data

Error message

unable to read inspect data: %w

What it means

Returned by `tryRawInspectFallback` (inspector.go:133-134) when `json.Decode(&raw)` fails on the raw inspect bytes. This path runs only after the typed template execution already failed, so the CLI tries to decode the raw payload as a generic interface; if that payload is not valid JSON (or is empty), decoding fails. The %w wraps the encoding/json error.

Solutions

1. Inspect without `--format` to confirm the raw response is valid: `docker inspect <ref>`.
2. Restart/reconnect to the daemon if responses are truncated.
3. Check for an intermediary (proxy, MITM) corrupting the response stream.
4. File a bug if the raw bytes are genuinely non-JSON for a supported resource.

Example fix

# before
docker inspect --format '{{.X}}' <ref>   # raw payload not JSON
# after
docker inspect <ref>                          # verify raw JSON first, then add --format

// validate raw inspect payload is JSON before templating
var probe any
if err := json.Unmarshal(rawElement, &probe); err != nil {
    return fmt.Errorf("raw inspect payload is not valid JSON; aborting template run: %w", err)
}

func isJSON(b []byte) bool {
    var v any
    return json.Unmarshal(b, &v) == nil
}

if err := inspector.Inspect(typed, raw); err != nil {
    if strings.Contains(err.Error(), "unable to read inspect data") {
        log.Warn("daemon returned non-JSON inspect data; retry without --format")
        return runInspectNoFormat(ref)
    }
    return err
}

When it happens

Trigger: A `getRef` implementation returns raw bytes that are not valid JSON while a custom `--format` template is used. Common in programmatically-driven inspect flows or when the daemon returns a truncated/corrupt response.

Common situations: Daemon returning a non-JSON error body, a proxy truncating the response, or a custom resource type whose raw form isn't JSON.

Related errors

• template parsing error
• failed to assemble ManifestDescriptor
• error reading plugin data
• failed to parse hook template
• unexpected hook response type

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/03b1a161fcd2f7f9. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/inspect/inspector.go:134

		}
		return i.tryRawInspectFallback(rawElement)
	}
	i.buffer.Write(buffer.Bytes())
	i.buffer.WriteByte('\n')
	return nil
}

// tryRawInspectFallback executes the inspect template with a raw interface.
// This allows docker cli to parse inspect structs injected with Swarm fields.
func (i *TemplateInspector) tryRawInspectFallback(rawElement []byte) error {
	var raw any
	buffer := new(bytes.Buffer)
	rdr := bytes.NewReader(rawElement)
	dec := json.NewDecoder(rdr)
	dec.UseNumber()

	if err := dec.Decode(&raw); err != nil {
		return fmt.Errorf("unable to read inspect data: %w", err)
	}

	tmplMissingKey := i.tmpl.Option("missingkey=error")
	if err := tmplMissingKey.Execute(buffer, raw); err != nil {
		return fmt.Errorf("template parsing error: %w", err)
	}

	i.buffer.Write(buffer.Bytes())
	i.buffer.WriteByte('\n')
	return nil
}

// Flush writes the result of inspecting all elements into the output stream.
func (i *TemplateInspector) Flush() error {
	if i.buffer.Len() == 0 {
		_, err := io.WriteString(i.out, "\n")
		return err
	}

View on GitHub (pinned to 4f84911bfe)