encode persisted client filesync mirror: nil mirror

Error message

encode persisted client filesync mirror: nil mirror

What it means

ClientFilesyncMirror.EncodePersistedObject refuses to encode a nil receiver. Persisted objects must be concrete instances with a stable client identity; encoding a nil pointer would produce a corrupt or unusable persisted record, so the library fails fast with this sentinel-style message.

Source

Thrown at core/client_filesync_mirror.go:108

		return 0, false, nil
	}
	size, err := snapshot.Size(ctx)
	if err != nil {
		return 0, false, err
	}
	return size, true, nil
}

type persistedClientFilesyncMirrorPayload struct {
	StableClientID string `json:"stableClientID"`
	Drive          string `json:"drive,omitempty"`
}

func (m *ClientFilesyncMirror) EncodePersistedObject(ctx context.Context, cache dagql.PersistedObjectCache) (dagql.PersistedObjectEncoding, error) {
	_ = ctx
	_ = cache
	if m == nil {
		return dagql.PersistedObjectEncoding{}, fmt.Errorf("encode persisted client filesync mirror: nil mirror")
	}
	if m.StableClientID == "" {
		return dagql.PersistedObjectEncoding{}, fmt.Errorf("encode persisted client filesync mirror: stable client id is empty")
	}
	m.mu.Lock()
	var links []dagql.PersistedSnapshotRefLink
	if m.snapshot != nil {
		links = []dagql.PersistedSnapshotRefLink{{
			RefKey: m.snapshot.SnapshotID(),
			Role:   "snapshot",
		}}
	}
	m.mu.Unlock()
	payload, err := json.Marshal(persistedClientFilesyncMirrorPayload{
		StableClientID: m.StableClientID,
		Drive:          m.Drive,
	})
	if err != nil {

View on GitHub (pinned to 82ba2681db)

Solutions

Ensure the mirror is initialized (e.g. NewEphemeralClientFilesyncMirror or the constructor your code uses) before it can be persisted
Add a nil check at the call site and skip persistence when the mirror is absent
Trace where the nil pointer came from and return an explicit error earlier instead of nil, nil

Example fix

// before
var mirror *ClientFilesyncMirror
_ = dagql.Persist(ctx, mirror)
// after
if mirror == nil {
    return errors.New("no client filesync mirror to persist")
}
_ = dagql.Persist(ctx, mirror)

Defensive patterns

Strategy: type-guard

Validate before calling

if mirror == nil {
    return errors.New("client filesync mirror not initialized")
}

Type guard

func isNilMirror(m *core.ClientFilesyncMirror) bool { return m == nil }

Try / catch

if err := persist(ctx, mirror); err != nil {
    if strings.Contains(err.Error(), "nil mirror") {
        // initialize and retry
    }
}

Prevention

Always construct mirrors via their constructor, never as bare nil fields
Nil-check optional mirror fields before triggering persistence
Return explicit errors instead of nil pointers from factory functions

When it happens

Trigger: Dagql attempts to persist a *ClientFilesyncMirror that is nil — e.g. an unset/optional field is being written to a cache or result ID store, calling EncodePersistedObject on a nil pointer.

Common situations: An optional ClientFilesyncMirror was never initialized before the query result was persisted; a code path returned a nil mirror without an error and downstream persistence assumed non-nil; API changes that made the field optional.

Related errors

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/f490018f68990485. Report an issue: GitHub.