mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-27 21:01:03 +08:00
748d708d53
## Summary Refreshes the docs around Stack Auth setup, CLI workflows, local development, the local emulator, known SDK errors, self-hosting, and the public showcase. This also wires the new docs into Mintlify navigation and normalizes `sharp` dependency resolution for docs/image tooling. Base: `dev` -> Head: `docs-mintlify/updates` Scope: 17 files, +1154 / -435 ## What's New - Adds a dedicated **Stack CLI** guide covering install, auth, init modes, project commands, config pull/push, `stack exec`, and emulator commands. - Adds a full **Local Emulator** guide for QEMU requirements, ports, default credentials, config-file backed projects, image pulls, state, and troubleshooting. - Reworks **Local Development** around two supported workflows: cloud-backed local dev and emulator-backed local dev, including app env vars, local config files, CI usage, and common failure modes. - Rewrites **Self-host** around the supported `stackauth/server` Docker deployment path, including Postgres, ClickHouse, cron scheduling, seeded admin access, reverse proxy setup, SDK env vars, email, webhooks, S3 storage, upgrades, and common issues. - Adds a **Known Errors** reference for public SDK-exposed known errors, runtime `errorCode` values, and REST API handling. - Clarifies **CLI App Authentication** so users can distinguish authenticating their own CLI app from using the official `stack` command. - Updates the JWT guide to remove the missing inline viewer reference and recommend an external JWT viewer. - Adds showcase cards for Browser Use and Overworld with supporting images and styles. - Pins `sharp` to `0.34.5` through pnpm overrides and lockfile cleanup. ## Review Notes - The self-host guide was audited against the current Docker entrypoint, server env templates, seed script, ClickHouse migration behavior, cron endpoints, and SDK API URL env resolution. - The Docker image starts the backend and dashboard, but not production schedulers, so the new cron section is called out explicitly. - Managed Domain email setup is documented as operator-managed because it depends on server-side Resend/DNSimple credentials; self-hosters are directed toward Custom SMTP or their own Resend API key. - `self-host-old.mdx` is kept as a legacy reference file and is not added to navigation. - `emulator run` documentation now matches CLI behavior: it stops the emulator only when it started that emulator instance. ## Test Plan - [x] Reviewed all files changed by `origin/dev...HEAD`. - [x] Ran `git diff --check origin/dev...HEAD`. - [x] Checked IDE diagnostics for the changed docs/CLI files. - [ ] Preview Mintlify docs locally and click through new navigation entries. - [ ] Verify showcase cards and images in light and dark themes. - [ ] Smoke-test the copied self-host commands in a non-production Docker environment. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added comprehensive Stack CLI, Local Emulator, Known Errors, and Local Development guides * Restructured Self-Hosting guide for production deployments and expanded authentication docs * Updated site navigation to include new guide pages * **New Features** * Added visual showcase section with responsive cards and hover/zoom interactions (and supporting styles) <!-- end of auto-generated comment: release notes by coderabbit.ai -->
84 lines
4.7 KiB
Plaintext
84 lines
4.7 KiB
Plaintext
---
|
|
title: "Known Errors"
|
|
description: "Reference for Stack Auth known errors exposed by public TypeScript SDK types"
|
|
sidebarTitle: "Known Errors"
|
|
---
|
|
|
|
Stack Auth uses known errors for expected, actionable failures. Some public SDK methods return `Result<..., KnownErrors["..."]>` in their TypeScript signatures. This page lists only the known errors currently exposed through those public TypeScript types.
|
|
|
|
<Info>
|
|
Stack Auth has additional internal known errors for API implementation details.
|
|
They are intentionally not part of this public SDK reference.
|
|
</Info>
|
|
|
|
At runtime, known errors include a stable `errorCode` value. In the REST API, the same value appears as the JSON `code` field and the `X-Stack-Known-Error` response header.
|
|
|
|
```json
|
|
{
|
|
"code": "EMAIL_PASSWORD_MISMATCH",
|
|
"error": "Wrong e-mail or password."
|
|
}
|
|
```
|
|
|
|
## Handling known errors
|
|
|
|
When using SDK methods that return `Result`, check `result.status` and inspect `result.error`.
|
|
|
|
```ts
|
|
const result = await stackClientApp.signInWithCredential({
|
|
email,
|
|
password,
|
|
});
|
|
|
|
if (result.status === "error") {
|
|
console.log(result.error.errorCode);
|
|
}
|
|
```
|
|
|
|
Check specific errors by comparing `error.errorCode`:
|
|
|
|
```ts
|
|
if (result.error.errorCode === "EMAIL_PASSWORD_MISMATCH") {
|
|
// Show "wrong email or password" UI.
|
|
}
|
|
```
|
|
|
|
For REST API calls, read the `code` field from the JSON response body.
|
|
|
|
<Info>
|
|
Error messages are human-readable and may include request-specific details.
|
|
Use `code` for programmatic handling.
|
|
</Info>
|
|
|
|
## Exposed known errors
|
|
|
|
| Public TypeScript type | Runtime `errorCode` | Returned by |
|
|
| --- | --- | --- |
|
|
| `KnownErrors["EmailPasswordMismatch"]` | `EMAIL_PASSWORD_MISMATCH` | `stackClientApp.signInWithCredential()` |
|
|
| `KnownErrors["InvalidTotpCode"]` | `INVALID_TOTP_CODE` | `stackClientApp.signInWithCredential()`, `stackClientApp.signInWithMagicLink()`, `stackClientApp.signInWithMfa()`, `stackClientApp.signInWithPasskey()` |
|
|
| `KnownErrors["UserWithEmailAlreadyExists"]` | `USER_EMAIL_ALREADY_EXISTS` | `stackClientApp.signUpWithCredential()` |
|
|
| `KnownErrors["PasswordRequirementsNotMet"]` | `PASSWORD_REQUIREMENTS_NOT_MET` | `stackClientApp.signUpWithCredential()`, `user.updatePassword()`, `user.setPassword()` |
|
|
| `KnownErrors["BotChallengeFailed"]` | `BOT_CHALLENGE_FAILED` | `stackClientApp.signUpWithCredential()`, `stackClientApp.sendMagicLinkEmail()` |
|
|
| `KnownErrors["PasskeyAuthenticationFailed"]` | `PASSKEY_AUTHENTICATION_FAILED` | `stackClientApp.signInWithPasskey()` |
|
|
| `KnownErrors["PasskeyRegistrationFailed"]` | `PASSKEY_REGISTRATION_FAILED` | `user.registerPasskey()` |
|
|
| `KnownErrors["PasskeyWebAuthnError"]` | `PASSKEY_WEBAUTHN_ERROR` | `stackClientApp.signInWithPasskey()`, `user.registerPasskey()` |
|
|
| `KnownErrors["CliAuthError"]` | `CLI_AUTH_ERROR` | `stackClientApp.promptCliLogin()` |
|
|
| `KnownErrors["CliAuthExpiredError"]` | `CLI_AUTH_EXPIRED_ERROR` | `stackClientApp.promptCliLogin()` |
|
|
| `KnownErrors["CliAuthUsedError"]` | `CLI_AUTH_USED_ERROR` | `stackClientApp.promptCliLogin()` |
|
|
| `KnownErrors["UserNotFound"]` | `USER_NOT_FOUND` | `stackClientApp.sendForgotPasswordEmail()` |
|
|
| `KnownErrors["RedirectUrlNotWhitelisted"]` | `REDIRECT_URL_NOT_WHITELISTED` | `stackClientApp.sendMagicLinkEmail()` |
|
|
| `KnownErrors["VerificationCodeError"]` | `VERIFICATION_ERROR` | `stackClientApp.resetPassword()`, `stackClientApp.verifyPasswordResetCode()`, `stackClientApp.verifyTeamInvitationCode()`, `stackClientApp.acceptTeamInvitation()`, `stackClientApp.getTeamInvitationDetails()`, `stackClientApp.verifyEmail()`, `stackClientApp.signInWithMagicLink()`, `stackClientApp.signInWithMfa()` |
|
|
| `KnownErrors["OAuthAccessTokenNotAvailable"]` | `OAUTH_ACCESS_TOKEN_NOT_AVAILABLE` | `connectedAccount.getAccessToken()`, `connectedAccount.useAccessToken()` |
|
|
| `KnownErrors["OAuthProviderAccountIdAlreadyUsedForSignIn"]` | `OAUTH_PROVIDER_ACCOUNT_ID_ALREADY_USED_FOR_SIGN_IN` | `oauthProvider.update()`, `serverOAuthProvider.update()`, `stackServerApp.createOAuthProvider()` |
|
|
| `KnownErrors["EmailAlreadyVerified"]` | `EMAIL_ALREADY_VERIFIED` | `user.sendVerificationEmail()` |
|
|
| `KnownErrors["PasswordConfirmationMismatch"]` | `PASSWORD_CONFIRMATION_MISMATCH` | `user.updatePassword()` |
|
|
|
|
## Parent error types
|
|
|
|
Some exposed types are parent classes for more specific errors. For example:
|
|
|
|
- `KnownErrors["PasswordRequirementsNotMet"]` may currently have `PASSWORD_TOO_SHORT` or `PASSWORD_TOO_LONG` as the runtime `errorCode`.
|
|
- `KnownErrors["VerificationCodeError"]` may currently have `VERIFICATION_CODE_NOT_FOUND`, `VERIFICATION_CODE_EXPIRED`, `VERIFICATION_CODE_ALREADY_USED`, or `VERIFICATION_CODE_MAX_ATTEMPTS_REACHED` as the runtime `errorCode`.
|
|
|
|
When you only need broad handling, check the parent type returned in TypeScript. When you need precise UI copy, compare `error.errorCode` against the specific runtime code.
|