It's not possible to use the deprecated Assets and AssetsHan

Error message

It's not possible to use the deprecated Assets and AssetsHandler options and the new AssetServer option at the same time. Please migrate all your Assets options to the AssetServer option.

What it means

BuildAssetServerConfig panics when the app options set both the new AssetServer option and either of the deprecated Assets / AssetsHandler options. Wails v2 migrated asset configuration to the unified AssetServer option, and mixing the two is ambiguous, so startup aborts with an explicit migration message.

Source

Thrown at v2/pkg/assetserver/common.go:20

import (
	"bytes"
	"errors"
	"io"
	"net/http"
	"strconv"
	"strings"

	"github.com/wailsapp/wails/v2/pkg/options"
	"github.com/wailsapp/wails/v2/pkg/options/assetserver"
	"golang.org/x/net/html"
)

func BuildAssetServerConfig(appOptions *options.App) (assetserver.Options, error) {
	var options assetserver.Options
	if opt := appOptions.AssetServer; opt != nil {
		if appOptions.Assets != nil || appOptions.AssetsHandler != nil {
			panic("It's not possible to use the deprecated Assets and AssetsHandler options and the new AssetServer option at the same time. Please migrate all your Assets options to the AssetServer option.")
		}

		options = *opt
	} else {
		options = assetserver.Options{
			Assets:  appOptions.Assets,
			Handler: appOptions.AssetsHandler,
		}
	}

	return options, options.Validate()
}

const (
	HeaderHost          = "Host"
	HeaderContentType   = "Content-Type"
	HeaderContentLength = "Content-Length"
	HeaderUserAgent     = "User-Agent"

View on GitHub (pinned to 0e754b1b40)

Solutions

Move the embedded FS into AssetServer.Assets and any handler into AssetServer.Handler
Delete the deprecated Assets and AssetsHandler fields from the options.App literal
Rebuild and confirm the app serves assets

Example fix

// before
err := wails.Run(&options.App{
    Assets:     assets,
    AssetServer: &assetserver.Options{Assets: assets},
})

// after
err := wails.Run(&options.App{
    AssetServer: &assetserver.Options{
        Assets:  assets,
        Handler: myHandler,
    },
})

Defensive patterns

Strategy: validation

Validate before calling

// fail fast before wails.Run
if appOpts.AssetServer != nil && (appOpts.Assets != nil || appOpts.AssetsHandler != nil) {
    log.Fatal("remove deprecated Assets/AssetsHandler; use AssetServer only")
}

Prevention

After adding AssetServer to options, grep the options literal for Assets: and AssetsHandler:
Follow the v2 migration notes when adopting AssetServer features (middleware, HookContext)

When it happens

Trigger: Passing options.App{AssetServer: &assetserver.Options{...}} while also setting Assets (an embed.FS/http.FS) or AssetsHandler in the same options struct.

Common situations: Upgrading a v2 app that had Assets: assets embedded, then adding AssetServer for middleware/HookContext features without removing the old fields; merging config from samples that use different option styles.

Related errors

AI-assisted analysis of wailsapp/wails@0e754b1b40 (2026-08-15). Data as JSON: /api/errors/4d9638f2430b4bb8. Report an issue: GitHub.