メインコンテンツにスキップ
バージョン: v2.8.1

トラブルシューティング

このページは、トラブルシューティングを手助けするヒント集です。

wailsコマンドが見つからないのですが?​

wailsコマンドが見つからないとシステムに怒られた場合は、Goが、公式のGoインストール手順に従って導入されているかを確認してください。 コマンドが見つからないほとんどの理由は、あなたのホームディレクトリ配下にあるgo/binディレクトリのパスが、PATH環境変数に含まれていないからです。 また、インストールによって行われた環境変更を反映させるために、もともと開いていたコマンドプロンプト(ターミナル)がある場合はそれらをいったん閉じて、再度開きなおしてください。

アプリケーションがホワイト/ブラックスクリーン表示になってしまいます​

アプリケーション内で、正しいディレクトリでアセットが指定されていることを確認してください。 main.goファイル内には、以下のようなコードが存在します:

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

また、frontend/distディレクトリ内に、アプリケーションアセットがきちんと含まれているか確認してください。

Mac​

この事象がMacで発生した場合は、Info.plistに以下の記述を追加してみてください:

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

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

Macのアプリケーションが無効になっています​

ビルドしたアプリケーションが次のように表示される場合:

アプリケーションのinfo.plistが無効である可能性があります。 build/<yourapp>.app/Contents/info.plistファイルを更新し、データが有効かどうかを確認します。たとえば、バイナリ名が正しいかどうかを確認してください。 変更を反映するには、ファイルをbuild/darwinディレクトリにコピーします。

Windowsのエクスプローラにアプリケーションアイコンが正しく表示されません​

アプリケーションアイコンが正しく表示されない場合は、C:\Users\&#060;あなたのユーザ名&#062;\AppData\Localディレクトリ内にある、IconCache.dbという隠しファイルを削除してみてください。 これにより、Windowsのアイコンキャッシュが強制的に再作成されます。

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

可変長引数を持つバックエンドメソッドをフロントエンドから呼び出せません​

次のように、可変長引数を持つバックエンドメソッドが定義されている場合:

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

このメソッドを、次のようにフロントエンドから呼び出すと失敗します:

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

回避方法:

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
  });

出典: https://github.com/wailsapp/wails/issues/1186

Wailsのインストール時にプロキシエラーが発生します​

次のようなエラーが発生する場合:

"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.

おそらく、公式のGo Proxyがブロックされています (中国のユーザより報告されています)。 解決するには、次のように、プロキシを手動で設定します:

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

出典: https://github.com/wailsapp/wails/issues/1233

生成されたTypeScriptの型定義が正しくありません​

場合によっては、生成されるTypeScriptの型定義が誤っていることがあります。 この事象を軽減させるために、ts_typeという構造体のタグを使用して、生成する型を指定することができます。 詳しくは、こちらをご覧ください。

index.htmlから移動するとフロントエンド上でメソッドを呼び出すことができません​

index.htmlから新しいhtmlファイルへ遷移すると、コンテキスト情報は失われてしまいます。 この事象を修正するには、遷移先の新しいページの<head>セクションに、次のインポートコードを追加します:

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

出典: https://github.com/wailsapp/wails/discussions/1512

Macでwails devを実行するとtoo many open filesエラーが発生します​

デフォルトでは、macOSは最大で256個のファイルしか開くことができません。 この制限により、wails devコマンド実行時に影響が発生する場合があります。 この制限は、ターミナルで次のようなコマンドを実行することで、緩和することができます: ulimit -n 1024。

FSNotifyは、Macのために、Appleのfseventsへの移行を検討しています。 この移行が完了しない間は、こちらで言及されているように、独自で実装を行います。

Macアプリで不可解なコンパイルエラーが発生します​

一部のユーザより、次のようなコンパイルエラーが発生することがあるという報告を受けています:

# github.com/wailsapp/wails/v2/internal/frontend/desktop/darwin
In file included from ../../pkg/mod/github.com/wailsapp/wails/[email protected]/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)))

これは一般的に、実行されているOSのバージョンと、インストールされているXCodeコマンドラインツールのバージョンが不一致であることが原因です。 このようなエラーが発生した場合は、XCodeコマンドラインツールを最新バージョンに更新してみてください。

XCodeコマンドラインツールの再インストールが引き続き失敗する場合は、次のコマンドを使用して、ツールキットがどこに配置されているかを確認できます:

xcode-select -p

/Applications/Xcode.app/Contents/Developerと表示された場合、sudo xcode-select --switch /Library/Developer/CommandLineToolsというコマンドを実行してください。

出典: https://github.com/wailsapp/wails/issues/1806 および https://github.com/wailsapp/wails/issues/1140#issuecomment-1290446496

My application won't compile on Mac​

次のようなエラーが発生する場合:

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"​

frontend/node_modulesとfrontend/package-lock.jsonを.gitignoreに追加することをお勧めします。 そうしないと、異なるバージョンのNodeがインストールされている別のマシンでリポジトリを開いた際に、アプリケーションが実行できなくなる場合があります。

この事象が発生した場合は、単純にfrontend/node_modulesとfrontend/package-lock.jsonを削除し、wails buildコマンドおよびwails devコマンドを再実行してください。

ビルドプロセスが"Generating bindings"で停止します​

バインディングの生成プロセスは、アプリケーションを特別なモードで実行します。 アプリケーションに、意図に有無にかかわらず無限ループ(wails.Run()のあとに終了されないコード)が含まれている場合、バインディングの生成の段階でビルドプロセスが停止する可能性があります。 コードが正しく終了していることを確認してください。

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.