Skip to main content
Версия: v2.11.0

Troubleshooting

An assortment of troubleshooting tips.

The wails command appears to be missing?​

If your system is reporting that the wails command is missing, make sure you have followed the Go installation guide correctly. Normally, it means that the go/bin directory in your User's home directory is not in the PATH environment variable. You will also normally need to close and reopen any open command prompts so that changes to the environment made by the installer are reflected at the command prompt.

My application is displaying a white/blank screen​

Check that your application includes the assets from the correct directory. In your main.go file, you will have something similar to the following code:

//go:embed all:frontend/dist
var assets embed.FS

Check that frontend/dist contains your application assets.

Mac​

If this happens on Mac, try adding the following to your Info.plist:

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

Reference: https://github.com/wailsapp/wails/issues/1504#issuecomment-1174317433

Mac application not valid​

If your built application looks like this in finder:

it's likely that your application's info.plist is invalid. Update the file in build/<yourapp>.app/Contents/info.plist and check if the data is valid, EG check the binary name is correct. To persist the changes, copy the file back to the build/darwin directory.

My application is not displaying the correct icon in Windows Explorer​

If your application is not displaying the correct icon, try deleting the hidden IconCache.db file located in the C:\Users\&#060;your username&#062;\AppData\Local directory. This will force Windows to rebuild the icon cache.

Source: https://github.com/wailsapp/wails/issues/2360#issuecomment-1556070036

Cannot call backend method from frontend with variadic arguments​

If you have a backend method defined with variadic parameters, eg:

func (a *App) TestFunc(msg string, args ...interface{}) error {
    // Code
}

calling this method from the frontend like this will fail:

var msg = "Hello: ";
var args = ["Go", "JS"];
window.go.main.App.TestFunc(msg, ...args)
  .then((result) => {
    //do things here
  })
  .catch((error) => {
    //handle error
  });

Workaround:

var msg = "Hello ";
var args = ["Go", "JS"];
window.go.main.App.TestFunc(msg, args)
  .then((result) => {
    //without the 3 dots
    //do things here
  })
  .catch((error) => {
    //handle error
  });

Credit: https://github.com/wailsapp/wails/issues/1186

I'm having getting proxy errors when trying to install Wails​

If you are getting errors like this:

"https://proxy.golang.org/github.com/wailsapp/wails/cmd/wails/@v/list": dial tcp 172.217.163.49:443: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.

it's probably because the official Go Proxy is being blocked (Users in China have reported this). The solution is to set up the proxy manually, eg:

go env -w GO111MODULE=on
go env -w GOPROXY=https://goproxy.cn,direct

Source: https://github.com/wailsapp/wails/issues/1233

The generated TypeScript doesn't have the correct types​

Sometimes the generated TypeScript doesn't have the correct types. To mitigate this, it is possible to specify what types should be generated using the ts_type struct tag. For more details, please read this.

When I navigate away from index.html, I am unable to call methods on the frontend​

If you navigate away from index.html to a new html file, the context will be lost. This can be fixed by adding the following imports to the <head> section of any new page you navigate to:

<head>
  <script src="/wails/ipc.js"></script>
  <script src="/wails/runtime.js"></script>
</head>

Source: https://github.com/wailsapp/wails/discussions/1512

I get too many open files errors on my Mac when I run wails dev​

By default, macOS will only allow you to open a maximum of 256 files. This can affect the wails dev command. This limit can be increased by running: ulimit -n 1024 in the terminal.

FSNotify is looking to move to Apple's fsevents for Mac. If this isn't completed soon, we will create our own implementation, tracked here.

My Mac app gives me weird compilation errors​

A few users have reported seeing compilation errors such as the following:

# github.com/wailsapp/wails/v2/internal/frontend/desktop/darwin
In file included from ../../pkg/mod/github.com/wailsapp/wails/v2@v2.0.0-beta.44.2/internal/frontend/desktop/darwin/callbacks.go:9:
In file included from /Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/Foundation.h:12:
/Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSBundle.h:91:143: error: function does not return NSString
- (NSAttributedString *)localizedAttributedStringForKey:(NSString *)key value:(nullable NSString *)value table:(nullable NSString *)tableName NS_FORMAT_ARGUMENT(1) NS_REFINED_FOR_SWIFT API_AVAILABLE(macos(12.0), ios(15.0), watchos(8.0), tvos(15.0));
                                                         ~~~~~~~~~~~~~~                                                                       ^                  ~
/Library/Developer/CommandLineTools/SDKs/MacOSX12.1.sdk/System/Library/Frameworks/Foundation.framework/Headers/NSObjCRuntime.h:103:48: note: expanded from macro 'NS_FORMAT_ARGUMENT'
        #define NS_FORMAT_ARGUMENT(A) __attribute__ ((format_arg(A)))

This is normally due to a mismatch with the OS version you are running and the version of the XCode Command Line Tools installed. If you see an error like this, try upgrading your XCode Command Line Tools to the latest version.

If reinstalling Xcode Command Tools still fails, you can check the path where the toolkit is located using:

xcode-select -p

If /Applications/Xcode.app/Contents/Developer is displayed, run sudo xcode-select --switch /Library/Developer/CommandLineTools

Sources: https://github.com/wailsapp/wails/issues/1806 and https://github.com/wailsapp/wails/issues/1140#issuecomment-1290446496

My application won't compile on Mac​

If you are getting errors like this:

l1@m2 GoEasyDesigner % go build -tags dev -gcflags "all=-N -l"
/Users/l1/sdk/go1.20.5/pkg/tool/darwin_arm64/link: running clang failed: exit status 1
Undefined symbols for architecture arm64:
  "_OBJC_CLASS_$_UTType", referenced from:
      objc-class-ref in 000016.o
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Ensure you have the latest SDK installed. If so and you're still experiencing this issue, try the following:

export CGO_LDFLAGS="-framework UniformTypeIdentifiers" && go build -tags dev -gcflags "all=-N -l"

Sources: https://github.com/wailsapp/wails/pull/2925#issuecomment-1726828562

--

Cannot start service: Host version "x.x.x does not match binary version "x.x.x"​

It's preferable to add frontend/node_modules and frontend/package-lock.json to your .gitignore. Otherwise when opening your repository on another machine that may have different versions of Node installed, you may not be able to run your application.

If this does happen, simply delete frontend/node_modules and frontend/package-lock.json and run your wails build or wails dev command again.

Build process stuck on "Generating bindings"​

Bindings generation process runs your application in a special mode. If application, intentionally or unintentionally, contains an endless loop (i.e. not exiting after wails.Run() finished), this can lead to build process stuck on the stage of bindings generation. Please make sure your code exits properly.

Mac application flashes white at startup​

This is due to the default background of the webview being white. If you want to use the window background colour instead, you can make the webview background transparent using the following config:

    err := wails.Run(&options.App{
        Title:  "macflash",
        Width:  1024,
        Height: 768,
        // Other settings
        Mac: &mac.Options{
            WebviewIsTransparent: true,
        },
    })

I get a "Microsoft Edge can't read or write to its data directory" error when running my program as admin on Windows​

You set your program to require admin permissions and it worked great! Unfortunately, some users are seeing a "Microsoft Edge can't read or write to its data directory" error when running it.

When a Windows machine has two local accounts:

  • Alice, an admin
  • Bob, a regular user

Bob sees a UAC prompt when running your program. Bob enters Alice's admin credentials into this prompt. The app launches with admin permissions under Alice's account.

Wails instructs WebView2 to store user data at the specified WebviewUserDataPath. It defaults to %APPDATA%\[BinaryName.exe].

Because the application is running under Alice's account, %APPDATA%\[BinaryName.exe] resolves to C:\Users\Alice\AppData\Roaming\[BinaryName.exe].

WebView2 creates some child processes under Bob's logged-in account instead of Alice's admin account. Since Bob cannot access C:\Users\Alice\AppData\Roaming\[BinaryName.exe], the "Microsoft Edge can't read or write to its data directory" error is shown.

Possible solution #1:

Refactor your application to work without constant admin permissions. If you just need to perform a small set of admin tasks (such as running an updater), you can run your application with the minimum permissions and then use the runas command to run these tasks with admin permissions as needed:

//go:build windows

package sample

import (
    "golang.org/x/sys/windows"
    "syscall"
)

// Calling RunAs("C:\path\to\my\updater.exe") shows Bob a UAC prompt. Bob enters Alice's admin credentials. The updater launches with admin permissions under Alice's account.
func RunAs(path string) error {
    verbPtr, _ := syscall.UTF16PtrFromString("runas")
    exePtr, _ := syscall.UTF16PtrFromString(path)
    cwdPtr, _ := syscall.UTF16PtrFromString("")
    argPtr, _ := syscall.UTF16PtrFromString("")

    var showCmd int32 = 1 //SW_NORMAL

    err := windows.ShellExecute(0, verbPtr, exePtr, argPtr, cwdPtr, showCmd)
    if err != nil {
        return err
    }
    return nil
}

Possible solution #2:

Run your application with extended permissions. If you absolutely must run with constant admin permissions, WebView2 will function correctly if you use a data directory accessible by both users and you also launch your app with the SeBackupPrivilege, SeDebugPrivilege, and SeRestorePrivilege permissions. Here's an example:

package main

import (
    "embed"
    "os"
    "runtime"

    "github.com/fourcorelabs/wintoken"
    "github.com/hectane/go-acl"
    "github.com/wailsapp/wails/v2"
    "github.com/wailsapp/wails/v2/pkg/options"
    "github.com/wailsapp/wails/v2/pkg/options/assetserver"
    "github.com/wailsapp/wails/v2/pkg/options/windows"
)

//go:embed all:frontend/dist
var assets embed.FS

const (
    fixedTokenKey = "SAMPLE_RANDOM_KEY"
    fixedTokenVal = "with-fixed-token"
    webviewDir    = "C:\\ProgramData\\Sample"
)

func runWithFixedToken() {
    println("Re-launching self")
    token, err := wintoken.OpenProcessToken(0, wintoken.TokenPrimary) //pass 0 for own process
    if err != nil {
        panic(err)
    }
    defer token.Close()

    token.EnableTokenPrivileges([]string{
        "SeBackupPrivilege",
        "SeDebugPrivilege",
        "SeRestorePrivilege",
    })

    cmd := exec.Command(os.Args[0])
    cmd.Args = os.Args
    cmd.Env = os.Environ()
    cmd.Env = append(cmd.Env, fmt.Sprintf("%v=%v", fixedTokenKey, fixedTokenVal))
    cmd.Stdin = os.Stdin
    cmd.Stdout = os.Stdout
    cmd.Stderr = os.Stderr
    cmd.SysProcAttr = &syscall.SysProcAttr{Token: syscall.Token(token.Token())}
    if err := cmd.Run(); err != nil {
        println("Error after launching self:", err)
        os.Exit(1)
    }
    println("Clean self launch :)")
    os.Exit(0)
}

func main() {
    if runtime.GOOS == "windows" && os.Getenv(fixedTokenKey) != fixedTokenVal {
        runWithFixedToken()
    }

    println("Setting data dir to", webviewDir)
    if err := os.MkdirAll(webviewDir, os.ModePerm); err != nil {
        println("Failed creating dir:", err)
    }
    if err := acl.Chmod(webviewDir, 0777); err != nil {
        println("Failed setting ACL on dir:", err)
    }

    app := NewApp()

    err := wails.Run(&options.App{
        Title:  "sample-data-dir",
        Width:  1024,
        Height: 768,
        AssetServer: &assetserver.Options{
            Assets: assets,
        },
        Bind: []interface{}{
            app,
        },
        Windows: &windows.Options{
            WebviewUserDataPath: webviewDir,
        },
    })

    if err != nil {
        println("Error:", err.Error())
    }
}

If you use a data directory accessible by both users but not the extended privileges, you will receive a WebView2 80010108 The object invoked has disconnected from its clients error.

Possible future solution #3: run WebView2 using an in-memory mode if implemented.

WebView2 installation succeeded, but the wails doctor command shows that it is not installed​

If you have installed WebView2, but the wails doctor command shows that it is not installed, it is likely that the WebView2 runtime installed was for a different architecture. You can download the correct runtime from here.

Source: https://github.com/wailsapp/wails/issues/2917

WebVie2wProcess failed with kind​

If your Windows app generates this kind of error, you can check out what the error means here.