Docs → Troubleshooting

Troubleshooting Guide

Common issues and their solutions when working with Swiftlets. Get unstuck and back to building amazing web apps.

🚨Common Problems

🔄

Build Hangs or Timeouts

Swift compiler gets stuck on complex HTML expressions, causing builds to hang indefinitely or timeout after 30 seconds.

❌

Type Checking Errors

Generic parameter inference failures when using conditionals or complex expressions in HTML builders.

🔧

Property Wrapper Issues

Incorrect syntax with @Query, @FormValue, @Cookie, or other property wrappers causing compilation errors.

📝

Method Not Found

Using outdated method names like .attr() instead of .attribute(), or missing imports.

🧠Expression Too Complex

The most common issue is Swift's type checker struggling with complex HTML structures. Here's how to fix it:

⚠️ When the build script times out after 30 seconds, it means your HTML structure is too complex for Swift's type checker. The solution is function decomposition.

Before: Problematic Code

Body {
    Nav {
        Container {
            HStack {
                Link(href: "/") { H1("Title") }
                Spacer()
                HStack(spacing: 20) {
                    Link(href: "/docs", "Docs")
                    Link(href: "/about", "About")
                    // Many more links...
                }
            }
        }
    }
    
    Container {
        VStack(spacing: 40) {
            Section {
                H2("Overview")
                P("Long content...")
                Grid(columns: .count(2)) {
                    // Many grid items...
                }
            }
            // Many more sections...
        }
    }
    
    Footer {
        // Complex footer...
    }
}

After: Decomposed Solution

@main
struct MyPage: SwiftletMain {
    var title = "My Page"
    
    var body: some HTMLElement {
        Fragment {
            navigation()
            mainContent()
            footer()
        }
    }
    
    @HTMLBuilder
    func navigation() -> some HTMLElement {
        Nav {
            Container {
                HStack {
                    Link(href: "/") { H1("Title") }
                    Spacer()
                    navigationLinks()
                }
            }
        }
    }
    
    @HTMLBuilder
    func navigationLinks() -> some HTMLElement {
        HStack(spacing: 20) {
            Link(href: "/docs", "Docs")
            Link(href: "/about", "About")
        }
    }
    
    @HTMLBuilder
    func mainContent() -> some HTMLElement {
        Container {
            VStack(spacing: 40) {
                overviewSection()
                detailsSection()
            }
        }
    }
}

🔨Common Build Errors

Generic parameter 'E' could not be inferred

Cause: Using 'if' statements in HTMLBuilder contexts

❌ Problematic
if showButton {
    Button("Click me")
}
✅ Correct
If(showButton) {
    Button("Click me")
}

Value of type 'Link' has no member 'attr'

Cause: Using outdated method names

❌ Problematic
Link(href: "/example", "Link")
    .attr("target", "_blank")
✅ Correct
Link(href: "/example", "Link")
    .attribute("target", "_blank")

Property wrapper initialization error

Cause: Incorrect property wrapper syntax

❌ Problematic
@Cookie var theme: String?
✅ Correct
@Cookie("theme", default: "light") var theme: String?

💡Quick Tips

1

Break Down Complex HTML

Use @HTMLBuilder functions returning 'some HTMLElement' for logical sections

2

Use If Helper

Replace 'if' statements with 'If()' helper in HTMLBuilder contexts

3

Check Method Names

Use .attribute() not .attr(), ensure you have the latest API

4

Property Wrapper Syntax

Include parameter names and defaults for @Cookie, @Query, etc.

5

Use .body for Components

Custom HTMLComponent instances need .body property or helper functions

6

Move Shared Code

Place reusable components in src/shared/ directory

❓Frequently Asked Questions

Why does my build hang indefinitely?

This usually happens when Swift's type checker encounters overly complex HTML expressions. Break your HTML into smaller @HTMLBuilder functions that return 'some HTMLElement'.

What's the difference between 'some HTML' and 'some HTMLElement'?

Use 'some HTMLElement' for @HTMLBuilder functions. 'some HTML' is for complete page structures. The type system expects HTMLElement in most contexts.

How do I debug what's causing a build timeout?

The build script will show which file is hanging. Look for deeply nested HTML, many chained modifiers, or complex expressions. Start by extracting the largest sections into separate functions.

Can I use regular Swift 'if' statements in HTML builders?

No, use the 'If()' helper instead. Regular 'if' statements cause generic parameter inference issues in result builder contexts.

Why can't I declare structs inside my HTML builder?

Swift's result builders don't allow declarations. Move your struct definitions outside the HTML builder closure or to separate files.

How do I know when to break down my HTML?

Consider decomposition when you have: 3-4+ levels of nesting, sections over 50-60 lines, multiple complex modifiers, or compilation taking more than a few seconds.

🆘Getting Help

Still Stuck?

If these solutions don't help, here are additional resources: