Handling EdgeSpark errors autonomously

Most errors in EdgeSpark have a clear cause and a clear fix. This page explains what each error means and how to resolve it without stopping for human input.

Type errors

Symptom: edgespark deploy or tsc fails during type checking. Cause: Code references a table, bucket, var, secret, or runtime import that does not match the repo-owned defs or generated SDK types. Fix:

edgespark pull types
cd server && npx tsc --noEmit

If the problem is schema-related, confirm that server/src/defs/db_schema.ts, server/src/defs/storage_schema.ts, and server/src/defs/runtime.ts match the code you wrote.

Migration errors

Symptom: Schema changes are not reflected in the database or deploy fails around migrations. Fix:

edgespark db generate
edgespark db check
edgespark db migrate

If destructive SQL is intentional, rerun with:

edgespark db migrate --confirm-dangerous

Build errors

Symptom: edgespark deploy fails at the build step.

Missing default app export

Fix: Ensure server/src/index.ts exports a default Hono app:

server/src/index.ts

import { Hono } from "hono";

const app = new Hono();

export default app;

Route outside `/api/*`

If deploy reports a route outside /api/*, move it under /api/*, /api/public/*, or /api/webhooks/*.

Bundle too large

Check for large dependencies or large static assets. See platform limits.

SQL validation rejections

Symptom: A request fails at runtime after a successful deploy. Common cases:

Code you wrote	What was blocked	Fix
`DELETE FROM posts` with no filter	Destructive DML	Add a `WHERE` clause or use `--confirm-dangerous` in CLI SQL
`DROP TABLE posts`	DDL at runtime	Use `edgespark db generate` and `edgespark db migrate`
`db.transaction(...)`	Transactions not supported	Use `db.batch([...])`
`PRAGMA ...`	Unsupported runtime SQL	Remove it from app code

Check the exact rejection with:

edgespark log tail

Runtime null errors

Symptom: A handler throws because a row or file does not exist. Fix:

const [post] = await db.select().from(posts).where(eq(posts.id, id));
if (!post) return c.json({ error: "Not found" }, 404);

const object = await storage.from(buckets.uploads).get(path);
if (!object) return c.json({ error: "File not found" }, 404);

Stale type warnings

Symptom: The CLI says local SDK types are stale. Fix:

edgespark pull types

To check without writing files:

edgespark pull types --check

When to stop and ask for human input

Stop and ask when:

You need the user to complete edgespark login
You need the user to set a secret value through the secure secret-entry flow
The next fix is destructive, such as dropping schema or deleting existing data

Declarative workflow

How defs, migrations, pulled schema, and generated types fit together.

Minimal human input

Which situations require stopping instead of fixing autonomously.

Overview

Working with EdgeSpark

Agent setup

Type errors

Migration errors

Build errors

Missing default app export

Route outside `/api/*`

Bundle too large

SQL validation rejections

Runtime null errors

Stale type warnings

When to stop and ask for human input

See also

Declarative workflow

Minimal human input

​Type errors

​Migration errors

​Build errors

​Missing default app export

​Route outside /api/*

​Bundle too large

​SQL validation rejections

​Runtime null errors

​Stale type warnings

​When to stop and ask for human input

​See also

Declarative workflow

Minimal human input

Type errors

Migration errors

Build errors

Missing default app export

Route outside `/api/*`

Bundle too large

SQL validation rejections

Runtime null errors

Stale type warnings

When to stop and ask for human input

See also