ipfs/kubo · error

invalid IPNS name

Error message

invalid IPNS name: %w

What it means

`ipfs ipns put` parses the given name argument with ipns.NameFromString after stripping the /ipns/ prefix. If the remaining string is not a valid IPNS name (expected to be a peer ID / public key form), the command wraps the parse error with this message.

Solutions

1. Pass the exact peer ID (public key) name the record was signed for, e.g. 12D3KooW... or its /ipns/ form
2. Verify the name with `ipfs key list` or `ipfs id` and copy it unmodified
3. If targeting a DNSLink name, note that ipns put requires a key-based name

Example fix

// before
ipfs ipns put /ipns/mydomain.example record.bin
// error: invalid IPNS name: ...
// after
ipfs ipns put /ipns/12D3KooWExamplePeerID... record.bin

namePart := strings.TrimPrefix(arg, "/ipns/")
if _, err := ipns.NameFromString(namePart); err != nil {
    return fmt.Errorf("not a valid key-based IPNS name: %w", err)
}

if _, err := ipns.NameFromString(strings.TrimPrefix(arg, "/ipns/")); err != nil {
    // surface a clear message: DNSLink names are not accepted by ipns put
}

When it happens

Trigger: `ipfs ipns put <name> ...` where <name> is not a valid libp2p public-key-based IPNS name — malformed peer ID, wrong multihash/multibase, or a path like /ipns/example.com that is a DNSLink name rather than a key name.

Common situations: Passing a DNS name (DNSLink) to ipns put, a typo'd or truncated peer ID, or a CID-based name that the ipns.Name parser does not accept.

Related errors

• cannot create new key
• cannot import key with name 'self'
• cannot specify negative resolve cache size
• cannot specify negative resolve cache size
• config setting IPNS.RecordLifetime

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

Appendix: source

Thrown at core/commands/name/name.go:473

			}
			delegatedPublishers := cfg.DelegatedPublishersWithAutoConf()
			if len(delegatedPublishers) == 0 {
				return errors.New("no delegated publishers configured: add Ipns.DelegatedPublishers or use --allow-offline for local-only publishing")
			}
			// For allow-delegated mode, we proceed even if offline
			// since we're using HTTP publishing via delegated publishers
		}

		// Parse the IPNS name argument
		nameArg := req.Arguments[0]
		if !strings.HasPrefix(nameArg, "/ipns/") {
			nameArg = "/ipns/" + nameArg
		}
		// Extract the name part after /ipns/
		namePart := strings.TrimPrefix(nameArg, "/ipns/")
		name, err := ipns.NameFromString(namePart)
		if err != nil {
			return fmt.Errorf("invalid IPNS name: %w", err)
		}

		// Read raw record bytes from file/stdin
		file, err := cmdenv.GetFileArg(req.Files.Entries())
		if err != nil {
			return err
		}
		defer file.Close()

		// Read record data (limit to 1 MiB for memory safety)
		data, err := io.ReadAll(io.LimitReader(file, 1<<20))
		if err != nil {
			return fmt.Errorf("failed to read record: %w", err)
		}
		if len(data) == 0 {
			return errors.New("record is empty")
		}

View on GitHub (pinned to 329838acdf)