Troubleshooting

Symptom-first fixes for auth, CRUD, storage, AI, realtime, and deployment issues

Use this page when something looks broken and you need the shortest safe path from symptom to fix. Each row keeps the public contract small: no provider keys, session tokens, storage grant URLs, database URLs, or internal platform paths should appear in app code, logs, screenshots, or support posts.

Fast Checks

Auth and API Base URL

Create one shared base URL and reuse it for auth lifecycle, queries, mutations, and realtime tickets.

// src/lib/gencow.ts
import { createAuthClient, createGencowClient } from "@gencow/client";
import { api } from "../gencow/api";

export const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:5456";
export const auth = createAuthClient(baseUrl);
export const apiClient = createGencowClient({ api, baseUrl, auth });

// src/main.tsx
import { GencowProvider } from "@gencow/react";
import { apiClient } from "./lib/gencow";

root.render(
    <GencowProvider apiClient={apiClient}>
        <App />
    </GencowProvider>
);

Do not rely on createAuthClient() to auto-read VITE_API_URL. Passing the URL explicitly is the stable contract.

CRUD Lists

createCrud().list returns an object with the rows and metadata. Treat it like a paginated result even when you only need the first page.

import { useQuery } from "@gencow/react";
import { api } from "../gencow/api";

export function TaskList() {
    const { data: result, isLoading, error } = useQuery(api.tasks.list, {});

    if (isLoading) return <p>Loading...</p>;
    if (error) return <p>Could not load tasks.</p>;
    if (!result || result.data.length === 0) return <p>No tasks yet.</p>;

    return (
        <ul>
            {result.data.map((task) => (
                <li key={task.id}>{task.title}</li>
            ))}
        </ul>
    );
}

For paging, pass page and limit and disable navigation when there is nowhere to go.

const limit = 20;
const { data: result } = useQuery(api.tasks.list, { page, limit });
const totalPages = Math.max(1, Math.ceil((result?.total ?? 0) / limit));

Storage 403s

Hosted storage is private by default. A private object should not be shown to the browser through a long-lived bare URL.

export const listFiles = procedure.query
    .name("files.list")
    .handler(async ({ context: ctx }) => {
        const rows = await ctx.db.select().from(files);
        return Promise.all(
            rows.map(async (row) => ({
                id: row.id,
                name: row.name,
                previewUrl: (await ctx.storage.createReadGrant(row.storageId, {
                    ttlSeconds: 300,
                    disposition: "inline",
                })).url,
            }))
        );
    });

Use ctx.storage.getPublicUrl(storageId) only for assets that were stored with { visibility: "public" }.

AI Errors

For cloud apps, use generated gencow/ai.ts or createGencowAI() helpers. Do not put provider SDK keys or raw provider clients in app code to work around errors.

Runtime 503s

APP_INFRA_UNAVAILABLE means the hosted runtime could not complete a platform-managed startup dependency and the platform considers the state retryable. Retry after the response delay, then check gencow deploy status and logs. If the app keeps returning the same code after platform status is healthy, redeploy with the latest CLI/runtime. Do not paste response bodies, logs, or screenshots that contain tokens, database URLs, storage grant URLs, or provider keys into public support channels.

CLI App Creation Errors

When gencow app create fails, the CLI exits unsuccessfully after printing the platform error. Preserve the Code and Correlation ID; they identify the exact request without exposing your login token. Run gencow app list before retrying so you do not create a duplicate after an uncertain network result.

If the message says App creation is temporarily unavailable, wait for platform recovery or contact support with only the safe error code, correlation ID, command time, CLI version, operating system, and runtime version. Do not send credential files, tokens, full environment dumps, or private deployment logs. A native runtime message printed after the platform error does not replace the first Code and Correlation ID as the support reference.

App creation itself does not start a runtime or allocate a tenant database. A runtime-capacity or deployment-executor issue should therefore appear during the first deployment, not as a partially created App. If an App exists but has not deployed successfully, it can still be deleted normally without requesting manual platform cleanup.

CLI Login Expired During Deploy

The CLI reports whether the rejected credential came from saved interactive login or an environment variable. For saved credentials, authenticate again against the same Platform:

npx gencow@latest login
npx gencow@latest whoami

If the message names GENCOW_TOKEN or GENCOW_DEPLOY_TOKEN, replace or unset that variable (or its CI secret) instead. Environment credentials override saved login credentials, so interactive login alone cannot replace an expired environment token. Never paste the token into a support request. If the CLI prints a correlation ID, share only that ID, the command time, Platform URL, CLI version, and operating system.

Deploy and Environment

Before deploying a frontend build, confirm the generated app talks to the intended backend:

VITE_API_URL=https://my-app.gencow.app bun run build
gencow deploy --static dist/

If auth works in development but not after static deploy, rebuild the frontend with the deployed VITE_API_URL and redeploy the static assets.

For cloud env changes, Stored means the encrypted catalog update succeeded. Runtime applied means a running backend acknowledged that exact revision. If the CLI prints an env operation ID, inspect it with:

gencow env status --operation envop_123