This guide lists every error message produced by leaf during detection and deployment, explaining why it occurred and how to resolve it.

Framework detection errors

No supported static-site framework detected. Use --dir to select a built output directory.

• Exit code: 3
• JSON error: {"error":"No supported static-site framework detected. Use --dir to select a built output directory.","schema":1}
• Why this happens: leaf deploy was run in a folder that does not contain a recognized static site configuration, lockfile, or root index.html.
• How to fix:
  • If your project is already built, specify the output folder: leaf deploy --dir dist (or leaf deploy dist). Passing --dir bypasses framework detection and sets the framework target to custom directory.
  • Or create a leaf.toml file in the project root with dir = "dist".
  • If deploying a plain HTML project, ensure an index.html file exists in the directory.
  • If deploying a project with a pre-built directory, use leaf deploy --no-build to skip the build step.

Next.js export errors

LeafCloud serves pre-rendered static sites. Next.js projects must be configured for static export.

Next.js must set output: 'export' to deploy as a static site

• Why this happens: Next.js defaults to server-side rendering unless static export is explicitly configured.
• How to fix: In your next.config.js (or next.config.mjs / next.config.ts), add output: 'export':

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    output: 'export',
  };
  module.exports = nextConfig;

Next.js server features cannot be deployed as a static site: API routes under app/api

• Why this happens: Next.js route handlers were found under app/api/.../route.ts (or route.js).
• How to fix: Move API route handlers to a dedicated backend service, or use client-side calls to external APIs.

Next.js server features cannot be deployed as a static site: API routes under pages/api

• Why this happens: Server API endpoints were found under pages/api/.
• How to fix: Remove pages/api endpoints or move them to an external backend service.

Next.js server features cannot be deployed as a static site: middleware

• Why this happens: A middleware.js or middleware.ts file was detected.
• How to fix: Static site deployments do not run dynamic server middleware. Remove middleware.ts and handle routing or authentication on the client side.

Next.js server features cannot be deployed as a static site: getServerSideProps

• Why this happens: One or more pages in the Pages router export getServerSideProps for server-side rendering.
• How to fix: Replace getServerSideProps with getStaticProps or static page exports.

Next.js server features cannot be deployed as a static site: server actions ('use server')

• Why this happens: A 'use server' directive was detected in your application source.
• How to fix: Use client-side event handlers and fetch calls to your API instead of server actions.

Next.js server features cannot be deployed as a static site: dynamic = 'force-dynamic'

• Why this happens: A route segment configures export const dynamic = 'force-dynamic'.
• How to fix: Remove force-dynamic to allow Next.js to pre-render the route at build time.

Next.js server features cannot be deployed as a static site: revalidate

• Why this happens: Incremental Static Regeneration (ISR) was configured using export const revalidate, revalidatePath, revalidateTag, or fetch(..., { next: { revalidate } }).
• How to fix: Remove revalidation settings. On LeafCloud, static deployments are refreshed each time you run leaf deploy.

Next.js server features cannot be deployed as a static site: next/image without images.unoptimized: true (<path>)

• Why this happens: next/image was imported without enabling unoptimized images. By default, Next.js requires a Node.js image optimization server.
• How to fix: In your next.config.js, configure images: { unoptimized: true }:

  const nextConfig = {
    output: 'export',
    images: {
      unoptimized: true,
    },
  };
  module.exports = nextConfig;

Build and directory errors

Use either a positional directory or --dir, not both.

• Why this happens: Both a positional path and the --dir option were supplied (e.g. leaf deploy dist --dir dist).
• How to fix: Use only one form: leaf deploy --dir dist or leaf deploy dist.

Output directory does not exist: <directory>

• Why this happens: The expected output folder (such as dist, build, or out) was not created by the build command, or a path specified in --dir does not exist.
• How to fix: Check that your build script finishes successfully and creates the output directory. Verify that dir in leaf.toml matches your build tool’s output setting.

The output directory contains no deployable files.

• Why this happens: The target output directory is completely empty or contains only hidden files (starting with .) and symlinks, which are ignored.
• How to fix: Check that your build process outputs static files (such as index.html, CSS, or JS bundles) into the target folder.

File exceeds your 25 MB per file limit

• Why this happens: One file in the output folder is larger than 25 MB, the most a single file can be. Files larger than 8 MB upload in resumable parts, so a dropped connection only re-sends the missing part.
• How to fix: Compress or split the file (for example, re-encode a video at a lower bitrate, or host a large download elsewhere and link to it). Very large media and datasets do not belong in a static site.

Build failed.

• Why this happens: The detected or configured build command returned a non-zero exit code.
• How to fix: Run your build command directly in your terminal (for example, npm run build or bun run build) to inspect the compiler or linter errors.

The build command in leaf.toml is empty.

• Why this happens: The build property in leaf.toml contains only whitespace.
• How to fix: Provide a valid command string (such as build = "npm run build") or delete the build line to use auto-detection.

Invalid leaf.toml line <line_number>

• Why this happens: Syntax error in leaf.toml.
• How to fix: Ensure each directive follows the key = "value" format. Strings must be enclosed in quotes.

Site selection and authentication errors

Create a site or set site = "name" in leaf.toml before deploying.

• Why this happens: You ran leaf deploy, but your account has no sites created yet and no leaf.toml target was specified.
• How to fix: Run leaf sites create <name> to create your first site, or add site = "<name>" to leaf.toml.

Set site = "name" in leaf.toml to choose a deployment target.

• Why this happens: Your account has multiple sites and leaf cannot guess which one to deploy to.
• How to fix: Add site = "<name>" to your leaf.toml file in the project root.

Not logged in. Run `leaf login` or set LEAF_TOKEN.

• Why this happens: No stored credentials were found in ~/.config/leaf/credentials.json, and LEAF_TOKEN was not set.
• How to fix: Run leaf login to sign in through your browser, or export LEAF_TOKEN="<secret>".

Pass --site when your account has zero or multiple sites.

• Why this happens: Commands like leaf deploys or leaf rollback were run without --site, and your account contains multiple sites.
• How to fix: Add --site <name>: leaf deploys --site my-site.