sv migrate - When Your Migration Goes Sideways

Your sv migrate finished running and now your app won't start. Welcome to migration hell. Here's the systematic approach I use to unfuck broken migrations, starting with the most common failures.

Step 1: Find Your Broken Shit

First thing - don't panic and start randomly fixing stuff. Get organized about what's actually broken:

## Find all the homework the migration tool left you
grep -r \"@migration\" src/

## Check for obvious build failures
npm run build 2>&1 | grep -E \"(error|ERROR)\"

## See what TypeScript is bitching about
npx tsc --noEmit

This gives you three categories of problems:

1. @migration comments - stuff the tool couldn't figure out
2. Build failures - broken imports, dependency issues, config problems
3. TypeScript errors - type mismatches from the component signature changes

Step 2: Fix Build Issues First (Before You Touch Components)

Don't waste time debugging components if your build is broken. Common build failures after migration:

Dependency version conflicts:

npm ls | grep UNMET
## Usually some library that expects Svelte 4

Package.json dependency hell:
The migration tool sometimes fucks up your versions. Check your package.json - if you see stuff like \"svelte\": \"^5.0.0\" but other packages pinned to old versions, you're gonna have problems.

Quick fix for most dependency issues:

rm package-lock.json node_modules -rf
npm install

If that doesn't work, you probably have a library that doesn't support Svelte 5 yet. Check the compatibility discussions, the framework compatibility tracker, or find an alternative.

Import errors:

Module not found: Error: Can't resolve 'svelte/internal'

This usually means you have old imports that didn't get migrated. The migration tool sometimes misses custom imports. Search your codebase:

grep -r \"svelte/internal\" src/
grep -r \"svelte/store\" src/ # sometimes breaks too

For detailed guidance on these import changes, see the official migration patterns and large application upgrade experiences.

Step 3: TypeScript Errors (The Migration Changed Component Types)

Svelte 5's TypeScript integration is stricter than Svelte 4. Common errors after migration:

Component props type errors:

// Error: Type '{ name: string }' is not assignable to type 'ComponentProps<MyComponent>'

This happens because component prop types changed from class-based to function-based. The fix depends on how you were typing props before.

Old Svelte 4 pattern:

// This breaks in Svelte 5
export interface Props {
  name: string;
}

New Svelte 5 pattern:

// This works
interface Props {
  name: string;
}

let { name }: Props = $props();

Dynamic component type errors:

// Error: ComponentType is deprecated
<svelte:component this={Component} />

The migration tool usually handles this but sometimes fucks it up. The new pattern:

// Import the new type
import type { Component } from 'svelte';

// Use it properly
<svelte:component this={Component as Component} />

Step 4: Runtime Errors (The Sneaky Shit)

Build passes, TypeScript is happy, but your app crashes at runtime. These are the worst because they're hard to debug.

Rune errors:

Error: Cannot read properties of undefined (reading '$state')

This usually means you have runes outside of component context. The migration tool sometimes moves $state calls to weird places.

Reactivity errors:

Error: Maximum call stack size exceeded

This is usually a circular dependency in your reactive statements. The migration tool sometimes creates infinite loops when converting complex $: patterns to $effect().

Finding the source:

## Look for suspicious $effect patterns
grep -A 5 -B 5 \"\$effect\" src/

## Check for circular dependencies
grep -r \"\$state.*\$derived\" src/

Step 5: Testing Failures (Because Of Course They Break Too)

Component tests often break after migration, even when the components work fine in the browser.

Common test failures:

Error: Cannot find module 'svelte/internal'
TypeError: component.$$set is not a function

This happens because test libraries sometimes lag behind Svelte versions. Solutions:

Update your testing library:

npm install @testing-library/svelte@latest

Or switch to the new browser-based testing:

npm install vitest-browser-svelte

The new browser testing approach actually works better with Svelte 5 runes because it tests in real browsers instead of jsdom. For detailed migration guides, see migrating from testing-library and the complete testing migration guide.

The Nuclear Option (When Everything's Still Broken)

If you're hours into debugging and nothing works:

## Back to square one
git checkout . && git clean -fd

## Try component-by-component migration
npx sv migrate --help # check for individual file options

Or migrate individual components using the VS Code extension's "Migrate Component" command. This lets you see exactly what changes before committing. For complex applications, consider the incremental migration approach used by production teams.

Pro Tips from Multiple Migrations

Migrate on a branch, always. I've seen people YOLO this on main and then spend 3 days rolling back.

Test incrementally. Don't migrate 50 components and then wonder what broke. Migrate 5, test, commit, repeat.

Check the browser console immediately. Lots of migration issues show up as console warnings before they become real errors.

Don't ignore deprecation warnings. They're telling you what will break in the next version.

The migration tool handles the mechanical stuff, but it can't read your mind about complex patterns. Plan for manual debugging time - it's not the tool's fault, it's just the reality of major version upgrades.

After debugging dozens of migrations, certain patterns break consistently. Here are the specific code patterns that trip up the migration tool and exactly how to fix them.

Complex Reactive Statements (The Migration Tool's Nemesis)

The tool handles simple $: doubled = count * 2 fine, but anything more complex usually gets an @migration comment.

Pattern that breaks:

<!-- Migration tool gives up here -->
$: {
  if (user?.isAuthenticated && permissions.length > 0) {
    const allowedActions = permissions.filter(p => p.active);
    if (allowedActions.some(a => a.type === 'admin')) {
      showAdminUI = true;
      loadAdminData();
    } else {
      showAdminUI = false;
      clearAdminData();
    }
  }
}

How to fix it manually:

<!-- Convert to $effect with proper dependencies -->
$effect(() => {
  if (user?.isAuthenticated && permissions.length > 0) {
    const allowedActions = permissions.filter(p => p.active);
    if (allowedActions.some(a => a.type === 'admin')) {
      showAdminUI = true;
      loadAdminData();
    }
    else {
      showAdminUI = false;
      clearAdminData();
    }
  }
});

Pro tip: The migration tool bails when it sees multiple statements, function calls, or complex conditionals. Break these into smaller, simpler reactive statements when possible. For detailed guidance on reactive statement conversion, see the runes introduction guide and $effect documentation.

Store Integration Patterns (Always Gets Fucked)

If your components have complex store interactions, migration often breaks the patterns.

Pattern that breaks:

<!-- Old Svelte 4 pattern -->
<script>
  import { myStore } from './stores.js';

  $: if ($myStore.user) {
    // Complex logic that depends on store value
    updateSomething($myStore.user.id);
    // Migration tool can't figure this out
  }
</script>

How to fix it:

<!-- New Svelte 5 pattern -->
<script>
  import { myStore } from './stores.js';

  // Subscribe properly to stores in Svelte 5
  let storeValue = $state();

  $effect(() => {
    return myStore.subscribe(value => {
      storeValue = value;
    });
  });

  $effect(() => {
    if (storeValue?.user) {
      updateSomething(storeValue.user.id);
    }
  });
</script>

Alternative approach: Keep using the $ syntax for simple store subscriptions - it still works in Svelte 5. For advanced store patterns with runes, see Svelte 5 store patterns and global state management strategies:

<script>
  import { myStore } from './stores.js';

  // This still works fine
  $effect(() => {
    if ($myStore.user) {
      updateSomething($myStore.user.id);
    }
  });
</script>

Component Communication Patterns (Event Dispatchers Break)

`createEventDispatcher` patterns often get mangled by migration.

Pattern that breaks:

<!-- Old pattern that confuses migration -->
<script>
  import { createEventDispatcher } from 'svelte';

  const dispatch = createEventDispatcher();

  function handleComplexEvent(data) {
    // Migration tool struggles with complex dispatch patterns
    if (data.isValid) {
      dispatch('success', {
        result: processData(data),
        timestamp: Date.now()
      });
    } else {
      dispatch('error', {
        message: 'Invalid data',
        details: data.errors
      });
    }
  }
</script>

Fixed pattern:

<!-- Convert to callback props (preferred in Svelte 5) -->
<script>
  let { onSuccess, onError } = $props();

  function handleComplexEvent(data) {
    if (data.isValid) {
      onSuccess?.({
        result: processData(data),
        timestamp: Date.now()
      });
    } else {
      onError?.({
        message: 'Invalid data',
        details: data.errors
      });
    }
  }
</script>

Lifecycle Hook Dependencies (Gets Messy)

When your onMount or lifecycle hooks have complex dependencies, migration often breaks the timing. For comprehensive lifecycle migration patterns, see the official migration guide and practical upgrade experiences.

Pattern that breaks:

<!-- Migration sometimes fucks up the timing -->
<script>
  import { onMount } from 'svelte';

  let data = [];
  let loading = true;

  onMount(async () => {
    // Complex async patterns confuse migration
    if (user?.authenticated && permissions.includes('read')) {
      try {
        data = await fetchUserData(user.id);
        loading = false;
      } catch (error) {
        handleError(error);
        loading = false;
      }
    }
  });
</script>

Fixed pattern:

<!-- Use $effect with proper dependencies -->
<script>
  let data = $state([]);
  let loading = $state(true);

  $effect(() => {
    if (user?.authenticated && permissions.includes('read')) {
      loading = true;

      fetchUserData(user.id)
        .then(result => {
          data = result;
          loading = false;
        })
        .catch(error => {
          handleError(error);
          loading = false;
        });
    }
  });
</script>

Dynamic Component Patterns (TypeScript Nightmare)

Dynamic components with complex props often break during migration. For detailed TypeScript migration guidance, see the Svelte 5 TypeScript documentation and component type migration examples.

Pattern that breaks:

<!-- TypeScript gets confused after migration -->
<script lang=\"ts\">
  import type { ComponentType } from 'svelte';

  // This type reference breaks in Svelte 5
  export let dynamicComponent: ComponentType;
  export let componentProps: Record<string, any>;
</script>

<svelte:component this={dynamicComponent} {...componentProps} />

Fixed pattern:

<!-- Use new Svelte 5 component typing -->
<script lang=\"ts\">
  import type { Component } from 'svelte';

  // New type system
  let {
    dynamicComponent,
    componentProps
  }: {
    dynamicComponent: Component;
    componentProps: Record<string, any>
  } = $props();
</script>

<svelte:component this={dynamicComponent} {...componentProps} />

Binding Edge Cases (Two-Way Binding Breaks)

Complex binding expressions often break subtly after migration. For detailed binding patterns and $derived usage, see the comprehensive examples and edge cases covered in migration discussions.

Pattern that breaks:

<!-- Complex binding that breaks -->
<script>
  let formData = { user: { profile: { name: '' } } };
</script>

<!-- This deep binding sometimes breaks -->
<input bind:value={formData.user.profile.name} />

Fixed pattern:

<!-- Flatten binding or use derived values -->
<script>
  let formData = $state({ user: { profile: { name: '' } } });

  // Create a derived binding
  let profileName = $derived.by(() => ({
    get value() { return formData.user.profile.name; },
    set value(newName) { formData.user.profile.name = newName; }
  }));
</script>

<input bind:value={profileName.value} />

The \"Everything Works But Tests Fail\" Pattern

Your components work in the browser but tests break because testing libraries don't understand the new patterns. For comprehensive testing migration strategies, see the testing library compatibility tracker and modern testing approaches.

What breaks in tests:

// Old test pattern that breaks
import { render } from '@testing-library/svelte';
import Component from './Component.svelte';

// This fails with Svelte 5 runes
const { component } = render(Component, { props: { name: 'test' } });
component.$set({ name: 'updated' }); // $$set doesn't exist anymore

Fixed test pattern:

// New test approach for Svelte 5
import { render } from '@testing-library/svelte';
import Component from './Component.svelte';

// Test behavior, not implementation
const { getByText, rerender } = render(Component, { name: 'test' });
expect(getByText('test')).toBeInTheDocument();

// Re-render with new props instead of using component methods
await rerender({ name: 'updated' });
expect(getByText('updated')).toBeInTheDocument();

Quick Debugging Checklist

When you hit a broken pattern:

1. Check the browser console first - lots of issues show as warnings before they become errors
2. Look for @migration comments - grep for them, they tell you exactly what the tool couldn't handle
3. Test in isolation - create a minimal reproduction in the Svelte Playground
4. Check the migration tool's source - look at `svelte-migrate` to understand what patterns it recognizes

Remember: The migration tool is conservative - it prefers leaving you @migration comments to breaking your app. Those comments are your roadmap to manual fixes.

Most broken patterns follow the same theme: the migration tool handles simple, isolated patterns well but struggles with complex, interconnected logic. When debugging, try to break complex patterns into simpler pieces first.