hashicorp/nomad · error

failed to decode 0.8 driver state: %v

Error message

failed to decode 0.8 driver state: %v

What it means

During pre-0.9 to modern state upgrades, UnmarshalPre09HandleID decodes a JSON-encoded 0.8-era driver task handle (TaskRunnerHandle08). This error wraps any json.Unmarshal failure, meaning the stored legacy driver state bytes are not valid JSON or do not match the expected handle schema.

Source

Thrown at client/state/08types.go:130

	// Strip so that it can be unmarshalled
	data := strings.TrimPrefix(t.HandleID, "DOCKER:")

	// The pre09 driver handle ID is given to the driver. It is unmarshalled
	// here to check for errors
	if _, err := UnmarshalPre09HandleID([]byte(data)); err != nil {
		return nil, err
	}

	ls.TaskHandle.DriverState = []byte(data)

	return ls, nil
}

// UnmarshalPre09HandleID decodes the pre09 json encoded handle ID
func UnmarshalPre09HandleID(raw []byte) (*TaskRunnerHandle08, error) {
	var handle TaskRunnerHandle08
	if err := json.Unmarshal(raw, &handle); err != nil {
		return nil, fmt.Errorf("failed to decode 0.8 driver state: %v", err)
	}

	return &handle, nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Inspect the raw 0.8 driver state file for valid JSON and expected fields (e.g. driver name, handle ID)
2. If the old task is no longer needed, remove the legacy state entry/data so upgrade skips it
3. Restore data_dir state files from backup before retrying client start
4. Check disk health / incomplete writes that may have truncated the state file

if len(raw) == 0 || !json.Valid(raw) {
    return nil, fmt.Errorf("skip invalid 0.8 driver state: %d bytes, not valid JSON", len(raw))
}

func isDecodable08Handle(raw []byte) bool {
    var h TaskRunnerHandle08
    return json.Unmarshal(raw, &h) == nil
}

handle, err := stateimpl.UnmarshalPre09HandleID(raw)
if err != nil {
    logger.Warn("legacy 0.8 driver state unreadable; skipping restore", "err", err)
    return nil // degrade gracefully rather than fail client startup
}

When it happens

Trigger: Client startup performs a state Upgrade and calls UnmarshalPre09HandleID on persisted pre-0.9 driver handles; the raw bytes are corrupt, truncated, empty, or were written by an incompatible format, so json.Unmarshal fails.

Common situations: Upgrading a very old Nomad client (0.8.x data_dir) whose state files are corrupted or partially written; manually copying/merging data_dir contents; disk corruption or interrupted writes on the legacy state store.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• error decoding stats data: stats were nil
• failed to clean task directories after failed migration: %v
• error parsing: root should be an object
• missing policy name
• cannot specify Accessor ID

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/8e93f89e5e6d8f66. Report an issue: GitHub.