{"record":{"id":"8725cb08e3e6e41e","repo":"stablyai/orca","slug":"authentication-required","errorCode":"authentication_required","errorMessage":"Sign in to Orca and try again.","messagePattern":"Sign in to Orca and try again\\.","errorType":"exception","errorClass":"RuntimeClientError","httpStatus":null,"severity":"error","filePath":"src/cli/handlers/artifacts.ts","lineNumber":161,"sourceCode":"    contentType,\n    fileName: remoteInput?.fileName ?? basename(sourceKey),\n    ...cloudOptions(ctx)\n  }\n  if (Buffer.byteLength(JSON.stringify(request), 'utf8') > ARTIFACT_CLI_MAX_RPC_BYTES) {\n    throw new RuntimeClientError(\n      'invalid_argument',\n      'Artifact is too large for the Orca CLI transport. Use the browser upload page instead.'\n    )\n  }\n  return request\n}\n\nfunction requireOperation<T>(operation: ArtifactCloudOperation<T>): T {\n  if (operation.status === 'ok') {\n    return operation.value\n  }\n  if (operation.status === 'reconnect-required') {\n    throw new RuntimeClientError('authentication_required', 'Sign in to Orca and try again.')\n  }\n  throw new RuntimeClientError('authentication_unconfigured', operation.message)\n}\n\nexport const ARTIFACT_HANDLERS: Record<string, CommandHandler> = {\n  'artifacts list': async (ctx) => {\n    rejectRemoteSelectionFlags(ctx)\n    const cursor = stringFlag(ctx, 'cursor')\n    const response = await ctx.client.call<ArtifactCloudOperation<ArtifactListPage>>(\n      'artifacts.list',\n      {\n        ...cloudOptions(ctx),\n        ...(cursor ? { cursor } : {})\n      }\n    )\n    const value = requireOperation(response.result)\n    printResult({ ...response, result: value }, ctx.json, formatArtifactListPage)\n  },","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/stablyai/orca/blob/1136503c6a231a16dce8f921f6fadb63d181e8db/src/cli/handlers/artifacts.ts#L143-L179","documentation":"Thrown by requireOperation() when an artifact cloud operation returns status 'reconnect-required', meaning the stored credentials are stale or revoked and the user must re-authenticate. This is distinct from 'authentication_unconfigured' (no credentials at all). It surfaces after an RPC like artifacts.list/share returns a non-ok operation status.","triggerScenarios":"Any artifacts command whose RPC response has result.status === 'reconnect-required': token expired, refresh failed, server reported revocation, or a password/SSO change invalidated the session. Fires in requireOperation() for list/share/update/unshare/delete.","commonSituations":"Long-lived CLI session where the OAuth token expired; user changed their Orca password or revoked the app; SSO provider session lapsed; the desktop client was signed out in the background.","solutions":["Run the Orca sign-in flow again (`orca login` or the desktop sign-in) and retry the artifacts command.","If sign-in repeatedly fails, check for a revoked/changed password or SSO policy change.","Confirm ORCA_CLOUD_AUTH_TOKEN (if used) is still valid; rotate it if expired.","After re-auth, verify with `orca artifacts list` before retrying the failing share/update."],"exampleFix":"# before\norca artifacts list   # ERROR authentication_required\n\n# after\norca login\norca artifacts list","handlingStrategy":"try-catch","validationCode":"// Cannot fully validate client-side; the host decides reconnect-required.\n// Mitigation: refresh credentials proactively before a batch.\nawait ensureSignedIn()","typeGuard":"const isReconnectRequired = (op: ArtifactCloudOperation<unknown>): boolean =>\n  op.status === 'reconnect-required'","tryCatchPattern":"try {\n  await dispatch('artifacts list', ctx)\n} catch (e) {\n  if (e instanceof RuntimeClientError && e.code === 'authentication_required') {\n    await signInAgain()\n    await dispatch('artifacts list', ctx) // retry once after re-auth\n  } else throw e\n}","preventionTips":["Re-authenticate before long-running batch jobs.","Surface 'sign in again' to the user immediately on this code.","Rotate ORCA_CLOUD_AUTH_TOKEN before it expires."],"tags":["artifacts","authentication","cloud","session-expired","auth"],"backgroundTag":null,"analyzedSha":"1136503c6a231a16dce8f921f6fadb63d181e8db","analyzedAt":"2026-08-12T23:15:58.167Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}