OpenNHP/opennhp · error

length exceeds maximum encoded value ( )

Error message

length %d exceeds maximum encoded value (%d)

What it means

Metadata chunk lengths are encoded into 2 bytes where the MSB is a continuation bit, leaving 15 bits of range (MetadataChunkMaxSize = 32767). encodeMetadataLength refuses any length above that maximum because it cannot be represented in the on-disk encoding. Callers like SetMetadata split large metadata into chunks; this error indicates a chunk bigger than the encoder supports.

Solutions

1. Split metadata into chunks of at most MetadataChunkMaxSize (32767) bytes, as SetMetadata does.
2. Use SetMetadata instead of calling the low-level encoder directly so chunking is handled for you.
3. Double-check that you pass the chunk length, not the total metadata length, to encodeMetadataLength.
4. If you need larger logical metadata, emit multiple continuation-chained chunks rather than one oversized chunk.

Example fix

// before
enc, err := encodeMetadataLength(len(bigMetadata), true) // fails if > 32767
// after
const chunkMax = 32767
for i := 0; i < len(bigMetadata); i += chunkMax {
    end := min(i+chunkMax, len(bigMetadata))
    cont := end < len(bigMetadata)
    enc, err := encodeMetadataLength(end-i, cont)
    // write chunk bigMetadata[i:end] ...
}

if len(meta) > 32767 {
    // split before encoding, as SetMetadata does
    chunks := (len(meta) + 32767 - 1) / 32767
}
// or per-chunk check:
if chunkLen > 32767 { return errors.New("chunk exceeds MetadataChunkMaxSize") }

enc, err := encodeMetadataLength(n, cont)
if err != nil {
    if strings.Contains(err.Error(), "exceeds maximum") {
        return fmt.Errorf("metadata chunk %d > %d; split it", n, 32767)
    }
    return err
}

When it happens

Trigger: Calling encodeMetadataLength (directly or via the anonymous function used by metadata processing) with length > 32767; building a single metadata chunk larger than MetadataChunkMaxSize instead of splitting it.

Common situations: Writing custom metadata handling that bypasses SetMetadata's chunk-splitting loop; computing a chunk size from a wrong constant (e.g. using 65535 for a '2-byte' length); passing a total metadata length instead of a per-chunk length.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• length is negative
• access url is empty, please check with data provider
• failed to download ztdo
• failed to parse ztdo header
• ztdo id mismatch, please check with data provider

AI-assisted analysis of OpenNHP/opennhp@6e04ca5ff0 (2026-09-07). Data as JSON: /api/errors/d66a537856497d5f. Report an issue: GitHub.

Appendix: source

Thrown at nhp/core/ztdo/ztdo.go:660

		newArray := reflect.New(arrayType).Elem()

		for i := range len {
			newArray.Index(i).SetUint(uint64(dst[i]))
		}

		rvalue.Set(newArray)

	} else {
		panic("not support")
	}
}

// encodeMetadataLength encodes a length continuation bit into the MSB of metadata length
func encodeMetadataLength(length int, continuation bool) ([2]byte, error) {
	var result [2]byte

	if length > MetadataChunkMaxSize {
		return result, fmt.Errorf("length %d exceeds maximum encoded value (%d)", length, MetadataChunkMaxSize)
	}

	if length < 0 {
		return result, fmt.Errorf("length %d is negative", length)
	}

	//nolint:gosec // G602: result is [2]byte array, indices 0 and 1 are always valid
	result[0] = byte((length >> 8) & 0x7F)
	if continuation {
		result[0] |= 0x80
	}
	result[1] = byte(length & 0xFF)

	if littleEndian {
		result[0], result[1] = result[1], result[0]
	}

	return result, nil

View on GitHub (pinned to 6e04ca5ff0)