oven-sh/bun · error · TypeError

bun-svelte-plugin: forceSide must be a string, got ${typeof

Error message

bun-svelte-plugin: forceSide must be a string, got ${typeof opts.forceSide}

What it means

validateOptions() for the Bun Svelte plugin checks every option before the plugin is constructed. When forceSide is provided (non-null) it must be a string; any other type (boolean, number, object) raises this TypeError at configuration time, before any build work starts.

Source

Thrown at packages/bun-plugin-svelte/src/options.ts:40

   */
  development?: boolean;

  /**
   * Options to forward to the Svelte compiler.
   */
  compilerOptions?: OverrideCompileOptions;
}

/**
 * @internal
 */
export function validateOptions(options: unknown): asserts options is SvelteOptions {
  assert(options && typeof options === "object", new TypeError("bun-svelte-plugin: options must be an object"));
  const opts = options as Record<keyof SvelteOptions, unknown>;

  if (opts.forceSide != null) {
    if (typeof opts.forceSide !== "string") {
      throw new TypeError("bun-svelte-plugin: forceSide must be a string, got " + typeof opts.forceSide);
    }
    switch (opts.forceSide) {
      case "client":
      case "server":
        break;
      default:
        throw new TypeError(`bun-svelte-plugin: forceSide must be either 'client' or 'server', got ${opts.forceSide}`);
    }
  }

  if (opts.compilerOptions) {
    if (typeof opts.compilerOptions !== "object") {
      throw new TypeError("bun-svelte-plugin: compilerOptions must be an object");
    }
  }
}

/**

View on GitHub (pinned to 8c5296ac45)

Solutions

1. Pass a string: 'client' or 'server'
2. Omit forceSide entirely to let the plugin infer the side from build flags
3. Type your config object as SvelteOptions so the mistake is caught at compile time

Example fix

// before
Bun.svelte({ forceSide: true });

// after
Bun.svelte({ forceSide: 'server' });

const opts: unknown = { forceSide: 'server' };
if ('forceSide' in (opts as object) && (opts as any).forceSide != null && typeof (opts as any).forceSide !== 'string') {
  throw new TypeError('forceSide must be a string');
}

function isSvelteOptions(o: unknown): o is BunSveltePlugin.SvelteOptions {
  if (!o || typeof o !== 'object') return false;
  const { forceSide, compilerOptions } = o as Record<string, unknown>;
  if (forceSide != null && typeof forceSide !== 'string') return false;
  if (compilerOptions != null && typeof compilerOptions !== 'object') return false;
  return true;
}

When it happens

Trigger: Calling Bun.svelte({ forceSide: true }), forceSide: 1, forceSide: ['client'], or any non-string value from untyped config (CLI flags parsed as booleans, JSON with wrong types).

Common situations: Users assuming forceSide is a boolean toggle; passing options parsed from CLI args or user JSON where 'true' became true; JS callers bypassing the SvelteOptions TypeScript types.

Related errors

• bun-svelte-plugin: compilerOptions must be an object
• bun-svelte-plugin: forceSide must be either 'client' or 'ser
• Virtual CSS module not found: ${path}
• Wrong first byte
• Wrong second byte

AI-assisted analysis of oven-sh/bun@8c5296ac45 (2026-08-16). Data as JSON: /api/errors/3fd2dd91f890a343. Report an issue: GitHub.