What causes "pin name is %d bytes (max %d bytes)" in ipfs/kubo?

Shorten the pin name to 255 bytes or fewer

pin name is %d bytes (max %d bytes)

Error message

pin name is %d bytes (max %d bytes)

What it means

ValidatePinName enforces the remote pinning API's maximum pin-name length of MaxPinNameBytes (255 bytes), measured in bytes, not characters. Names longer than the limit are rejected because remote pin services (per the Pinning Services API) would fail to accept them. Empty names are allowed.

Source

Thrown at core/commands/cmdutils/utils.go:67

	// Block size is limited to SoftBlockLimit (2MiB) as defined in the bitswap spec.
	// https://specs.ipfs.tech/bitswap-protocol/#block-sizes
	if size > SoftBlockLimit {
		return fmt.Errorf("produced block is over 2MiB: big blocks can't be exchanged with other peers. consider using UnixFS for automatic chunking of bigger files, or pass --allow-big-block to override")
	}
	return nil
}

// ValidatePinName validates that a pin name does not exceed the maximum allowed byte length.
// Returns an error if the name exceeds MaxPinNameBytes (255 bytes).
func ValidatePinName(name string) error {
	if name == "" {
		// Empty names are allowed
		return nil
	}

	nameBytes := len([]byte(name))
	if nameBytes > MaxPinNameBytes {
		return fmt.Errorf("pin name is %d bytes (max %d bytes)", nameBytes, MaxPinNameBytes)
	}
	return nil
}

// PathOrCidPath returns a path.Path built from the argument. It accepts a
// content path (/ipfs/cid), a native IPFS URI (ipfs://cid, ipns://name, and the
// schemeless ipfs:cid / ipns:name forms), or a bare CID string.
func PathOrCidPath(str string) (path.Path, error) {
	p, err := path.NewPathFromURI(str)
	if err == nil {
		return p, nil
	}

	// Save the original error before attempting fallback
	originalErr := err

	if p, err := path.NewPath("/ipfs/" + str); err == nil {
		return p, nil

View on GitHub (pinned to 329838acdf)

Solutions

Shorten the pin name to 255 bytes or fewer
Hash/abbreviate long identifiers (e.g. use a truncated CID or checksum) in generated names
For multibyte names, count bytes (utf8.RuneCountInString is not enough) before submitting

Example fix

// before
name := "pin:" + strings.Repeat("ä", 300)
// after
if len([]byte(name)) > 255 {
    name = name[:200] // or truncate on a rune boundary to stay <= 255 bytes
}

Defensive patterns

Strategy: validation

Validate before calling

const maxPinNameBytes = 255
if len([]byte(name)) > maxPinNameBytes {
    name = truncateToByteLimit(name, maxPinNameBytes)
}

Try / catch

if err := cmdutils.ValidatePinName(name); err != nil {
    return fmt.Errorf("pin name rejected: %w; shorten the name and retry", err)
}

Prevention

Truncate generated names to <=255 bytes before calling pin remote add
Count bytes, not runes, for multibyte names
Hash long identifiers into short pin names

When it happens

Trigger: `ipfs pin remote add --name=<long-name>` or lsRemote filtering with a name over 255 bytes; non-ASCII names that exceed 255 bytes even with few characters (multibyte runes count fully).

Common situations: Auto-generated pin names embedding long paths/URLs; CJK or emoji names where 100+ characters exceed 255 bytes; CI pipelines naming pins with full artifact paths.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/fdb4e2a111f50da2. Report an issue: GitHub.