benbjohnson/litestream · error

invalid filename in path %s: %w

Error message

invalid filename in path %s: %w

What it means

parseLTXPath could not parse the filename component of a NATS object path as an LTX range. The path matched ltx/<level>/ but the third segment is not a valid <minTXID>-<maxTXID>.ltx pair (ltx.ParseFilename failed), so a listed object in the store does not follow the LTX naming convention.

Source

Thrown at nats/replica_client.go:276

		objPath = strings.TrimPrefix(objPath, c.Path+"/")
	}

	// Expected format: "ltx/<level>/<minTXID>-<maxTXID>.ltx"
	parts := strings.Split(objPath, "/")
	if len(parts) < 3 || parts[0] != "ltx" {
		return 0, 0, 0, fmt.Errorf("invalid ltx path: %s", objPath)
	}

	// Parse level
	if level, err = strconv.Atoi(parts[1]); err != nil {
		return 0, 0, 0, fmt.Errorf("invalid level in path %s: %w", objPath, err)
	}

	// Parse filename (minTXID-maxTXID.ltx)
	filename := parts[2]
	minTXIDVal, maxTXIDVal, err := ltx.ParseFilename(filename)
	if err != nil {
		return 0, 0, 0, fmt.Errorf("invalid filename in path %s: %w", objPath, err)
	}

	return level, minTXIDVal, maxTXIDVal, nil
}

// LTXFiles returns an iterator of all LTX files on the replica for a given level.
// NATS always uses accurate timestamps from headers since they're included in LIST operations at zero cost.
// The useMetadata parameter is ignored.
func (c *ReplicaClient) LTXFiles(ctx context.Context, level int, seek ltx.TXID, useMetadata bool) (ltx.FileIterator, error) {
	if err := c.Init(ctx); err != nil {
		return nil, err
	}

	// List all objects in the store
	internal.OperationTotalCounterVec.WithLabelValues(ReplicaClientType, "LIST").Inc()
	objectList, err := c.objectStore.List(ctx)
	if err != nil {
		// NATS returns "no objects found" when bucket is empty, treat as empty list

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Remove or rename non-LTX objects in the NATS object store under the replica path
2. Check for manually uploaded or leftover files with malformed names

When it happens

Trigger: Thrown at nats/replica_client.go:276 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/bc9d2b9a28a53d81. Report an issue: GitHub.