Common mistakes

A short cookbook of the failures newcomers hit most often. Pair it with Configuration and the Misconfiguration notes on <authui-config>.

Endpoint without /v1

Appwrite's HTTP API lives under /v1. If you pass https://cloud.appwrite.io (or your self-hosted host) without that suffix, Auth UI shows a single sticky config error banner asking you to end the endpoint with /v1.

// Wrong
AuthUI.init({ endpoint: "https://cloud.appwrite.io", project: "…" });

// Right
AuthUI.init({ endpoint: "https://cloud.appwrite.io/v1", project: "…" });

Regional Cloud endpoints look like https://fra.cloud.appwrite.io/v1. Auth UI also warns in the console when the endpoint does not end with /v1.

Hostname not registered as a Web platform

Auth UI runs on your origin. Appwrite rejects requests from hosts that are not listed under Overview → Integrations → Platforms. Add a Web platform for localhost (and your production hostname) before testing, or the first account.get() fails with general_unknown_origin.

Methods enabled in the UI but not in the Console

methods on <authui-config> / AuthUI.init() only controls which buttons Auth UI shows. Each method must also be enabled under Auth → Settings in the Appwrite Console (and each OAuth provider must be configured with client IDs). Otherwise the UI looks ready and the request fails at runtime.

CDN URL: use the CDN builds, not dist/authui.js

Bare unpkg / jsDelivr package URLs and the dedicated CDN files are safe in a <script> tag. The package main / module file (dist/authui.js) is a bundler entry: it has a bare import "appwrite", so loading it from a CDN fails with Failed to resolve module specifier "appwrite" and custom elements never upgrade.

<!-- Safe ESM CDN: elements only. Configure with <authui-config>. -->
<script type="module" src="https://unpkg.com/@getauthui/core@0.1.45"></script>
<authui-config endpoint="…" project="…"></authui-config>

<!-- Safe IIFE CDN: use window.AuthUI from a classic script. -->
<script src="https://unpkg.com/@getauthui/core@0.1.45/dist/authui.cdn.js"></script>
<script>
  AuthUI.init({ endpoint: "…", project: "…" });
</script>

<!-- Wrong: package main / bundler build on a CDN -->
<!-- <script type="module" src="https://unpkg.com/@getauthui/core@0.1.45/dist/authui.js"></script> -->

With a bundler, prefer import { AuthUI } from "@getauthui/core". Pin a version on the CDN in production.

Protected content flashes (FOUC)

The in-module FOUC guard cannot run until the script loads. Load the shipped FOUC stylesheet in <head> before the Auth UI script so <authui-show> children stay hidden (same rules as CRITICAL_FOUC_CSS):

<link rel="stylesheet" href="https://unpkg.com/@getauthui/core@0.1.45/dist/fouc.css" />

Bundlers: import "@getauthui/core/fouc.css".

See <authui-show>. In React, use the Show wrapper from @getauthui/core/react so children are not mounted while hidden.

Building custom login forms

Auth UI already covers email/password, magic URL, email OTP, phone, anonymous, OAuth and MFA. Do not rebuild those forms yourself. Use <authui-button>, <authui-sign-in> or AuthUI.open(), and let the Appwrite SDK own the session. Never pass session secrets or JWTs through URLs.

For apps that only need the session (no Auth UI chrome), call AuthUI.init() / AuthUI.on("signed-in", …) and still skip hand-rolled credential forms.

Related

• Getting started
• AI agents
• Security notes