HKUDS/Vibe-Trading · error · ValueError

connection credential_ref does not match its local transport

Error message

connection credential_ref does not match its local transport

What it means

Raised when a connection's credential_ref does not equal the deterministic reference _credential_reference(profile.id, connection_id) expected for its transport. The parser tolerates the legacy local CredentialStore.reference(connection_id) form only for local_plugin profiles (migrating it automatically); any other mismatch is rejected to prevent a connection from reading secrets scoped to a different transport/profile.

Source

Thrown at agent/src/trading/connections.py:330

            )
        label = str(raw.get("label") or profile.label).strip()
        if (
            not label
            or len(label) > 80
            or any(ord(character) < 32 for character in label)
        ):
            raise ValueError(
                "connection label must contain 1 to 80 printable characters"
            )
        expected_ref = _credential_reference(profile.id, connection_id)
        credential_ref = str(raw.get("credential_ref") or expected_ref)
        if (
            credential_ref == CredentialStore.reference(connection_id)
            and profile.transport != "local_plugin"
        ):
            credential_ref = expected_ref
        if credential_ref != expected_ref:
            raise ValueError(
                "connection credential_ref does not match its local transport"
            )
        return TradingConnection(
            id=connection_id,
            profile_id=profile.id,
            label=label,
            credential_ref=credential_ref,
            created_at=str(raw.get("created_at") or _now()),
        )

    def _write(self, connections: list[TradingConnection]) -> None:
        """Atomically rewrite the registry file with owner-only permissions.

        Args:
            connections: Full set of connections to persist.
        """
        self.path.parent.mkdir(parents=True, exist_ok=True)
        descriptor, temporary = tempfile.mkstemp(

View on GitHub (pinned to 80ffdda44c)

Solutions

Remove the credential_ref key so it defaults to the computed expected reference
Or set credential_ref to _credential_reference(profile.id, connection_id) for the entry's actual profile and id
If secrets were stored under the old reference, re-store the credentials under the expected reference (or via store.create) before fixing the JSON
Avoid hand-editing credential_ref; always create/update connections through the store API

Example fix

// before
{"id": "alpaca", "profile_id": "live-readonly", "credential_ref": "cred:other-conn"}

// after
{"id": "alpaca", "profile_id": "live-readonly"}  // credential_ref defaults to the computed reference

Defensive patterns

Strategy: validation

Validate before calling

from trading.connections import _credential_reference
expected = _credential_reference(profile_id, connection_id)
if raw.get("credential_ref", expected) != expected:
    raw.pop("credential_ref", None)  # let it default to the computed reference

Try / catch

try:
    store.save(entries)
except ValueError as exc:
    if "credential_ref" in str(exc):
        for e in entries:
            e.pop("credential_ref", None)
        store.save(entries)
    else:
        raise

Prevention

Never hand-edit credential_ref; omit it and let the store compute it
Re-create credentials through the store after changing a connection's profile
Treat credential_ref mismatches as a security signal — audit before auto-fixing

When it happens

Trigger: A settings entry with a hand-edited or stale credential_ref naming another connection's or profile's secret slot, or a non-local_plugin profile still carrying the old CredentialStore.reference(connection_id) value plus a second mismatching override. Hit during _parse from list() or save().

Common situations: Copying a settings file between connections or profiles without updating credential_ref; changing a connection's profile in the JSON but not its credential_ref; leftover refs after a secrets-store migration or profile rename.

Related errors

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/ecaec2dfb87bd382. Report an issue: GitHub.