Exception thrown if app starts while no displays connected on macOS

[kirb]

Describe the bug

The way CVDisplayLink is used inside PlatformRenderTimer.mm can cause the app to crash on startup, because it expects a display to immediately be available. This is not always the case - our app can update and restart itself automatically, which can happen during Power Nap, when the laptop lid is closed and no external displays are attached.

System.InvalidOperationException: Avalonia.Native was not able to start the RenderTimer. Native error code is: -6661
  ?, in void AvaloniaNativeRenderTimer.add_Tick(Action<TimeSpan> value)
  ?, in void ThreadProxyRenderTimer.add_Tick(Action<TimeSpan> value)
  ?, in void RenderLoop.Add(IRenderLoopTask i)
  ?, in new ServerCompositor(IRenderLoop renderLoop, IPlatformGraphics platformGraphics, CompositionOptions options, BatchStreamObjectPool<object> batchObjectPool, BatchStreamMemoryPool batchMemoryPool)
  ?, in new Compositor(IRenderLoop loop, IPlatformGraphics gpu, bool useUiThreadForSynchronousCommits, ICompositorScheduler scheduler, bool reclaimBuffersImmediately, Dispatcher dispatcher, CompositionOptions options) x 3
  ?, in void AvaloniaNativePlatform.DoInitialize(AvaloniaNativePlatformOptions options)
  ?, in AvaloniaNativePlatform AvaloniaNativePlatform.Initialize(IntPtr factory, AvaloniaNativePlatformOptions options) x 2
  ?, in AppBuilder AvaloniaNativePlatformExtensions.UseAvaloniaNative(AppBuilder builder)+() => { }
  ?, in void AppBuilder.SetupUnsafe()
  ?, in void AppBuilder.Setup()
  ?, in AppBuilder AppBuilder.SetupWithLifetime(IApplicationLifetime lifetime)
  ?, in int ClassicDesktopStyleApplicationLifetimeExtensions.StartWithClassicDesktopLifetime(AppBuilder builder, string[] args, Action<IClassicDesktopStyleApplicationLifetime> lifetimeBuilder)
  ?, in void Program.Main(string[] args)

This seems related to, or possibly the same as, #14927.

To Reproduce

Repro steps are a bit annoying given the nature of the edge case. This might be sufficient:

1. Build any Avalonia app. The absolute barebones Avalonia .NET App template will work.
2. Create the following shell script:

while true; do
	./MyAvaloniaApp & pid=$!
	sleep 10
	kill $pid
done

3. Run the script.
4. Close the lid and disconnect all cables (displays/power) from the laptop, but keep it in Wi-Fi range.
5. Wait some time for Power Nap to happen.

Expected behavior

The app consistently launches 100% of the time. No exceptions are logged in the terminal window.

Avalonia version

11.3.0

OS

macOS

Additional context

We worked around the crash with the following, which we call in Program.Main() just before BuildAvaloniaApp():

[SupportedOSPlatform("macos")]
public static partial class CVDisplayLink
{
	private const string CoreVideoLibrary = "/System/Library/Frameworks/CoreVideo.framework/CoreVideo";

	[LibraryImport(CoreVideoLibrary)]
	private static partial int CVDisplayLinkCreateWithActiveCGDisplays(out IntPtr displayLinkOut);

	[LibraryImport(CoreVideoLibrary)]
	private static partial void CVDisplayLinkRelease(IntPtr displayLink);

	/// <summary>
	/// Loop until a display link is available. If no displays are connected, this will wait until one does connect.
	/// </summary>
	public static async Task AwaitDisplayLink()
	{
		IntPtr displayLink;
		while (CVDisplayLinkCreateWithActiveCGDisplays(out displayLink) != 0) {
			await Task.Delay(1000);
		}

		CVDisplayLinkRelease(displayLink);
	}
}

[kirb]

Another potential repro I thought of but haven’t tested: Run the app from SSH, while at the login window with no users logged in.

[drasticactions]

@kirb I think you're right that #14927 is the same as your issue.

That error is kCVReturnInvalidArgument (which would jive with what's happening here since there are no active displays, they're off.), and those CoreVideo APIs are all deprecated in 15.0 (And, annoyingly, the replacments mentioned were introduced in 14.0 going by the docs)

[kirb]

Figured out something far more reproducible: Apple Silicon machines wake up for a decent period of time when an APNS push notification is received, such as an iMessage. This gives a time window where apps can unexpectedly do work while the lid is closed. Our use case wants the app to update as soon as possible (and we do all the right things like acquiring a power assertion), but I could see someone, say, launching a binary with Avalonia GUI from a cron script or SSH’d in, and rather than it doing some expected task, it crashes because the GUI can’t start.

[brianwphamSF]

We're hitting this in production on Avalonia 11.3.x from a different angle
that I think is worth folding into the fix scope before any patch lands —
the CGGetActiveDisplayList-based retry sketched above won't cover it.

Distinct fingerprint. On macOS 15.7.x bare metal and on Apple-Virt /
Parallels guests we observe CGMainDisplayID() == 0 while
CGGetActiveDisplayList() returns a non-empty list of active displays.
WindowServer is in a transient demote-promote race where the previous main
display has been demoted but the new one hasn't been promoted yet — the
window normally closes in microseconds but on these hosts it can stretch
into seconds, and occasionally doesn't close at all until forced by another
display reconfig. So a retry that waits for CGGetActiveDisplayList().count > 0
exits immediately and the -6661 from CVDisplayLinkCreateWithActiveCGDisplays
still trips.

The same wedge state also crashes a second Avalonia code path that's not
captured in this issue: WindowBaseImpl's initial-frame computation
dereferences [NSScreen screens], which is empty in the wedge window, and
throws Sequence contains no matching element before any UI appears. Any
fix shape worth landing should defend both code paths since they share the
trigger.

Most reliable repro is a coordinated host + guest display sleep on
Parallels — the host-side step matters; sleeping only inside the guest
puts the virtual display to sleep but doesn't drive Parallels' display
backend into the same state, and the wedge fires far less often:

1. Inside the Parallels guest, sleep the virtual display:

   pmset displaysleepnow

2. On the Parallels host (the outer macOS running Parallels Desktop),
   sleep the host via the Apple-menu Sleep item, the lid (for
   laptops), or:

   pmset sleepnow

3. Wait ~2 minutes for both to reach full display sleep (not just dim) —
   shorter waits don't reliably reach the wedge state.

4. Wake the host first (key / mouse), then bring the Parallels guest
   window back into focus.

5. Inside the guest, launch any Avalonia 11.3.x app:

   ./bin/Debug/net8.0/ControlCatalog.Desktop

Roughly 1-in-3 launches under this sequence trip both the
PlatformRenderTimer -6661 and the WindowBaseImpl empty-screens crash
in the same process. The wedge frequently persists across multiple
launches until something forces a CGS reconfig (window resize, display
arrangement change, scrolling through System Settings → Displays). On
macOS 15.7.x bare metal we observe the same fingerprint less reliably
after pmset displaysleepnow and wake without the host-side coordination.

Workaround we ship today (mentioned for context, not as a model for the
upstream fix):

• An Obj-C dylib that swizzles -[NSWindow _initContent:...] to substitute
  a default frame when [NSScreen screens] is empty, so window
  construction survives the wedge window. Validates that defending
  WindowBaseImpl.Init against empty screens is safe.
• A privileged userland helper that detects the wedge fingerprint
  (CGMainDisplayID() == 0 && CGGetActiveDisplayList().count > 0) and
  clears it with a tiered display-mode toggle. Not appropriate for
  Avalonia upstream — UI frameworks shouldn't toggle the user's display
  mode unsolicited — but mentioned so it's clear the fingerprint is real
  and recoverable in production.

Suggested fix shape that handles both this issue's "no displays" case
and the wedge case:

1. native/Avalonia.Native/src/OSX/PlatformRenderTimer.mm — on
   CVDisplayLinkCreateWithActiveCGDisplays failure, register
   CGDisplayRegisterReconfigurationCallback and wait up to a configurable
   timeout for either a reconfig event or
   CGGetActiveDisplayList().count > 0 && CGMainDisplayID() != 0 (both
   conditions, not just the active-list count). On final timeout, fall
   back to an NSTimer-based 60Hz render timer rather than throwing —
   this is the path Chromium takes when CV is unavailable
   (reference).
2. native/Avalonia.Native/src/OSX/WindowBaseImpl.mm and the C# Screens
   plumbing — defensive empty-screens handling: synthesize a sentinel
   (0, 0, 800, 600) rect on the Obj-C side and a synthetic primary
   Screen on the C# side (matching what the Win32 / X11 backends already
   do), so Screens.All.First(...) paths can't throw when AppKit reports
   zero screens.

CVDisplayLink* is deprecated in macOS 15.0 and the CADisplayLink-on-macOS
replacement only exists from 14.0 onward, so the migration is a separate
larger piece of work that I'd suggest not gating this fix on.

Happy to author both layers as a draft PR if no one is already on it — the
swizzle workaround above is essentially Layer 2 of this fix done out-of-tree
and we'd rather retire it. Let me know either way.

---

Update — May 27. Drafted both layers and pushed them to my fork.
Reviewable as a single commit on the compare view (no PR open yet — happy
to open one whenever there's a green light):

master...brianwphamSF:Avalonia:fix/macos-cgs-wedge-render-timer

A couple of intentional deviations from the suggested shape above worth
flagging:

• The WindowImplBase change ended up on the C# side
  (src/Avalonia.Native/WindowImplBase.cs), not the .mm side. Tracing
  the Sequence contains no matching element crash, the actual call site
  is C# Init enumerating AllScreens via
  .First(m => m.Bounds.Contains(Position)). The C++ WindowBaseImpl.mm
  constructor already absorbs the empty-screens case with its hardcoded
  (0,0) position and (100,100) size fallbacks, so no synthetic-NSScreen
  sentinel was needed on the native side. Switched the C# line to the same
  defensive FirstOrDefault + Math.Max(..., 300/200) pattern
  X11Window.cs already uses
  for its equivalent code path.

• The PlatformRenderTimer.mm change dropped the "configurable timeout /
  strict main-display gating" step from the sketch above. Just letting the
  NSTimer fallback drive frames until any CGDisplayRegisterReconfigurationCallback
  fires successfully turned out simpler and has equivalent behavior in
  practice — the wedge always ends in a reconfig sooner or later, and the
  upgrade is gated by CVDisplayLinkCreateWithActiveCGDisplays succeeding
  on that callback, which implicitly enforces the "displays settled" check.
  The new destructor also incidentally fixes a pre-existing leak —
  _displayLink was never released by the previous class.

No tests in the draft: Avalonia.Native doesn't have an obvious unit-test
harness for the native render-timer, and Appium-based integration tests
can't deterministically force the wedge fingerprint. The C# Init change
could plausibly be Headless-covered if useful. Happy to add coverage in
whatever shape makes sense.

Happy to open a PR whenever you're ready, or to adjust the shape first
(e.g. opt-in flag for the NSTimer fallback, different floor on the C#
side, folding in the CADisplayLink migration as a separate commit on
the same branch, ...). Let me know either way.

[timunie]

Feel free to open a PR anyways. This makes review and feedback easier and creates a package for testing.

[brianwphamSF]

Feel free to open a PR anyways. This makes review and feedback easier and creates a package for testing.

Sounds good! Here's the PR: #21453