docker/cli · error

read exceeds the defined limit

Error message

read exceeds the defined limit

What it means

Returned by the internal limitedReader.Read when its remaining byte counter N has gone negative, meaning more bytes were read than the configured cap. This reader wraps tar/zip import streams to enforce a maximum import size; exceeding the limit is treated as a hard error rather than silently truncating.

Solutions

1. Reduce the archive size below the import limit; remove large or unrelated files before exporting.
2. Re-export the context from the source to produce a minimal archive containing only meta.json and tls/ files.
3. Inspect the archive contents to confirm it is a legitimate context export.

// Reject oversized archives before importing.
const maxImport = maxAllowedFileSizeToImport
if size, err := archiveSize(path); err == nil && size > maxImport {
    return fmt.Errorf("archive %d bytes exceeds import limit %d", size, maxImport)
}

When it happens

Trigger: Importing a docker context archive (tar or zip) larger than maxAllowedFileSizeToImport. The reader decrements N per read; once N drops below zero on a subsequent read this error fires. Triggered by 'docker context import' (or the store.Import path) on an oversized archive.

Common situations: A crafted or accidental context archive that exceeds the safety limit. A context export that accidentally bundled large unrelated files.

Related errors

• unexpected context file
• unexpected path format
• %s: %w
• unexpected '\\' in path
• invalid context: no metadata found

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

Appendix: source

Thrown at cli/context/store/io_utils.go:17

package store

import (
	"errors"
	"io"
)

// limitedReader is a fork of [io.LimitedReader] to override Read.
type limitedReader struct {
	R io.Reader
	N int64 // max bytes remaining
}

// Read is a fork of [io.LimitedReader.Read] that returns an error when limit exceeded.
func (l *limitedReader) Read(p []byte) (n int, err error) {
	if l.N < 0 {
		return 0, errors.New("read exceeds the defined limit")
	}
	if l.N == 0 {
		return 0, io.EOF
	}
	// have to cap N + 1 otherwise we won't hit limit err
	if int64(len(p)) > l.N+1 {
		p = p[0 : l.N+1]
	}
	n, err = l.R.Read(p)
	l.N -= int64(n)
	return n, err
}

View on GitHub (pinned to 4f84911bfe)