babalae/better-genshin-impact · error · Win32Exception

临时解除本地鼠标限制失败

Error message

临时解除本地鼠标限制失败

What it means

LocalCursorCapture.ReleaseTemporarily calls the Win32 ClipCursor(NULL) to lift the local cursor restriction. If the native call fails it throws a Win32Exception carrying Marshal.GetLastPInvokeError(). This is a genuine OS-level failure (e.g. permission, session state) rather than a caller-input problem; the method only attempts the call when a restriction was previously applied.

Source

Thrown at BetterGenshinImpact/Core/Monitor/LocalCursorCapture.cs:91

        _appliedBounds = bounds;
        if (!_isRestrictionApplied)
        {
            HideCursor();
            _isRestrictionApplied = true;
        }
    }

    internal void ReleaseTemporarily()
    {
        ObjectDisposedException.ThrowIf(_isDisposed, this);
        if (!_isCaptureSessionActive || !_isRestrictionApplied)
        {
            return;
        }

        if (!NativeMethods.ReleaseClipCursor(IntPtr.Zero))
        {
            throw new Win32Exception(
                Marshal.GetLastWin32Error(),
                "临时解除本地鼠标限制失败");
        }

        var centerX = _appliedBounds.Left + _appliedBounds.Width / 2;
        var centerY = _appliedBounds.Top + _appliedBounds.Height / 2;
        if (!NativeMethods.SetCursorPos(centerX, centerY))
        {
            logger.LogWarning(
                "将本地鼠标移动到桌面分身控件中心失败，Win32Error: {Win32Error}",
                Marshal.GetLastWin32Error());
        }

        RestoreCursorVisibility();
        _isRestrictionApplied = false;
        _appliedBounds = Rectangle.Empty;
    }

View on GitHub (pinned to a7cb36712d)

Solutions

1. Wrap the release call in try/catch (Win32Exception) and log the native error code.
2. Verify the process runs in an interactive desktop session with normal privileges.
3. Disable other cursor-clipping/overlay tools that may conflict.

Example fix

// before
_cursorCapture.ReleaseTemporarily();

// after
try
{
    _cursorCapture.ReleaseTemporarily();
}
catch (Win32Exception ex)
{
    logger.LogWarning("释放鼠标限制失败 Win32Error={Code}", ex.NativeErrorCode);
}

try
{
    _cursorCapture.ReleaseTemporarily();
}
catch (System.ComponentModel.Win32Exception ex)
{
    logger.LogWarning("释放鼠标限制失败 Win32Error={Code}", ex.NativeErrorCode);
    // continue; cursor restriction may already be gone
}

When it happens

Trigger: ClipCursor(NULL) returning false because the process lacks access in the current desktop/session; calling release during session shutdown; antivirus/hook interference intercepting ClipCursor.

Common situations: Running under a restricted desktop or via RDP/remote session where cursor clipping is policy-limited; third-party overlay tools conflicting; UAC/elevation boundary differences.

Related errors

• 鼠标限制区域必须具有有效宽度和高度。
• 注册 Raw Input 鼠标设备失败
• Raw Input 采集线程初始化超过 {InitializationTimeout.TotalSeconds:0} 秒
• Raw Input 初始化失败
• 不支持的相对鼠标输入类型

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/39cd89339bdefa1f. Report an issue: GitHub.