uWS.getParts gives zero copy references; need copy or neutering

[pavel-nekrasov1]

Description

uWebSockets.js crashes with a segmentation fault (SIGSEGV) on macOS 26.1 (Tahoe) with Apple Silicon. The same code runs without issues on macOS 15 (Sequoia).

Environment

• OS: macOS 26.1 (Build 25B78) - ARM64 Apple Silicon (Mac16,7)
• Node.js versions tested: v20.19.0, v20.19.5, v22.x
• uWebSockets.js versions tested: v20.51.0, v20.56.0
• Architecture: arm64 (native, not Rosetta)

Steps to Reproduce

1. Install uWebSockets.js v20.56.0 on macOS 26
2. Run any application using uWebSockets.js
3. Perform some I/O operations (in our case, processing data after an HTTP request)
4. Crash occurs during event loop processing

Expected Behavior

Application runs without crashing.

Actual Behavior

Segmentation fault: 11
Exit code: 139

The crash occurs after successful operation completion, when control returns to the event loop.

Crash Report Details

From macOS crash report:

Exception Type: EXC_BAD_ACCESS (SIGSEGV)
Exception Subtype: KERN_INVALID_ADDRESS at 0x000000787e73683c

Crashed Thread: 12 (worker thread)

Crashing binary: uws_darwin_arm64_127.node (also tested uws_darwin_arm64_115.node)

Stack trace (faulting thread):
- Builtins_KeyedLoadIC_Megamorphic
- Builtins_GetKeyedPropertyHandler
- Builtins_InterpreterEntryTrampoline
- Builtins_AsyncFunctionAwaitResolveClosure
- Builtins_PromiseFulfillReactionJob
- Builtins_RunMicrotasks
- v8::internal::MicrotaskQueue::RunMicrotasks
- ... (event loop / worker thread stack)

Binaries Tested

Both ABI 115 (Node 20.x) and ABI 127 (Node 22.x) binaries crash on macOS 26:

• uws_darwin_arm64_115.node - crashes
• uws_darwin_arm64_127.node - crashes

Workaround

Currently using macOS 15 or running in Docker/Linux containers.

Notes

• A colleague running the exact same code on macOS 15 with the same Node.js version has no issues
• The precompiled ARM64 binaries for macOS appear to be incompatible with macOS 26's runtime
• The crash happens in V8 microtask processing, suggesting possible memory corruption or ABI incompatibility in the native module

Request

Could the ARM64 macOS binaries be recompiled with macOS 26 SDK support?

[uNetworkingAB]

This is a "it crashes, please fix" kind of bug report. Those are entirely unusable by themselves.

Crashed Thread: 12 (worker thread)

How did you manage to have 12 threads?

[pavel-nekrasov1]

@uNetworkingAB I am not sure about threads, as I am not manually controlling it.

Use case is: 10 xlsx files are uploaded through POST request (files are attached as form-data), then they are being processed 1 by 1. As soon as the first file is being processed, node.js backend is being crashed. As I have tested, files themselves, their order or size do not matter, crash always happens after the backend starting to process the second one.

The workaround is to upload one file

[peterlodri92]

the prebuilt native binary (uws_darwin_arm64_*.node) was compiled against an older macOS SDK, and something changed in macOS 26 that breaks it.

The fact that identical code works perfectly on macOS 15 but dies on macOS 26 pretty much rules out any bug in the user's code. This is almost certainly Apple changing something under the hood with how native addons work, and the uWebSockets binaries haven't caught up yet.

imo maintainers need to rebuild the macOS ARM64 binaries using the macOS 26 SDK

some digging:

• The insta segfault on macos Tahoe hashcat/hashcat#4511 shows a similar crash pattern - native code calling into Apple frameworks (Metal in their case) that changed behavior in macOS 26. They had to disable a Metal optimization flag that worked fine on older macOS versions.

• From a https://groups.google.com/g/CLIPSESG/c/d8WnnrOu8n8: "Tahoe may use a different range group granularity (larger chunks reserved at once), so when [app] asks for more memory, the allocator can run out of contiguous space sooner."

• Every major macOS release rebuilds the dyld shared cache. If uWebSockets was built against older SDK assumptions about library layouts or symbol resolution, it could cause crashes during dynamic linking or lazy symbol resolution.

• MacPorts Tahoe Problems: https://trac.macports.org/wiki/TahoeProblems (documents C++ header and SDK issues)

• Hashcat Segfault Fix: insta segfault on macos Tahoe hashcat/hashcat#4511 (similar native module crash, fixed by disabling
  SDK-specific optimizations)

• Apple macOS 26 Release Notes: https://developer.apple.com/documentation/macos-release-notes/macos-26-release-notes

• Xcode 26 Release Notes: https://developer.apple.com/documentation/xcode-release-notes/xcode-26-release-notes

[uNetworkingAB]

the prebuilt native binary (uws_darwin_arm64_*.node) was compiled against an older macOS SDK, and something changed in macOS 26 that breaks it.

No, this is not how any of this works. No platform in the history of computers work like this.

The fact that identical code works perfectly on macOS 15 but dies on macOS 26 pretty much rules out any bug in the user's code.

No, it does not rule anything out. This is not how native code works. A "crash" isn't something idetifiable other than once it triggers a segfault. Your code is broken on the old platform as well, you just don't catch it in any identifiable way.

None of those links are in any way relevant. A segfailt is not some kind of identifiable error, it's just the end of the line catch-all final break once the app has gone so broken that it cannot roll down a hill any more.

This is a bug in uWS code, with highest probability due to your excessive use of threads - 12 of them, it's thread 12 that segfauts, and the only question that matters is how you managed to create those. The threading balancing support in uWS is experimental, so if that is used. This issue is entirely unworkable until you present the thread creation code. Also, if you have other native addons.

[uNetworkingAB]

What you need to do:

• Drop this whole stubborn compilation thing, it's not how things work.
• Reduce your code to some small reproducer by stripping out as much as possible.
• Recompile uWS with AddressSanitizer and catch the issue (I can probably do this if you strip out enough stuff, we're talking 0 dependencies and small reproducer)

[uasan]

I also have MacOS 26, and reading the request body works without problems.

[uNetworkingAB]

Yes it has nothing to do with compilation or platform and the provided "crash" is not even where it goes wrong. That's just where the final catch-all breaker triggers.

In native code, a "crash" stacktrace rarely (if ever) actually corresponds with the bug. This is a major difference between scripts (a crash = where the issue is) and native code (there really isn't any such thing as a "crash", it's just the kernel freaking out when things have gone so massively wrong it would be a security issue to continue.

Whether or not the bug is caught can be due to platform differences but that's just a symptom to the issue, not the actual issue. The bug still exists on all platforms. Your code is still fully broken on the old platform as well.

[pavel-nekrasov1]

Updated Bug Report for uWebSockets.js Maintainer

Environment

• macOS: 26.1 (Tahoe) - stable release, ARM64 Apple Silicon
• Node.js: v20.19.0, v20.19.5, v22.x (all crash)
• uWebSockets.js: v20.51.0, v20.56.0 (both crash)
• Other native addon: pg (PostgreSQL client)

---

Thread Question Answered

"How did you manage to have 12 threads?"

We use Node.js worker_threads. In DEV mode we spawn 1 worker thread:

import { Worker, isMainThread, parentPort } from 'worker_threads'

if (isMainThread) {
    const worker = new Worker(__filename)  // Single worker
} else {
    // uWebSockets runs HERE, inside the worker thread
    const uWS = (await import('uWebSockets.js')).default
    uWS.App().post('/upload', ...).listen(9999)
}

"Thread 12" in the crash report is macOS's internal thread numbering, not our explicit thread count.

---

Business Logic & Workload

Use case: Bulk import of commercial real estate data via HTTP file upload.

Workload:

• 10 xlsx files uploaded in single multipart POST request
• Each file: ~30MB compressed, ~50,000 rows, 50+ columns
• Total: ~300MB upload, ~500,000 database records

Processing pattern:

1. Receive multipart body, parse with uWS.getParts()
2. For each xlsx file buffer from getParts():
   • Parse with xlsx library (30MB → ~300MB in memory during parse)
   • Insert 50,000 rows to PostgreSQL (chunks of 50, Promise.all)
3. Crash occurs after file 1 completes, during/before file 2

---

Systematic Debugging Results

Test Configuration	Worker	uWS	pg	xlsx	Multipart Upload	Result
Original app	✅	✅	✅	✅	✅ Real files	❌ CRASH
server-single-pool.js	✅	✅	✅	✅	✅ Real files	❌ CRASH
server-no-worker.js	❌	✅	✅	✅	✅ Real files	✅ No crash
test-no-uws.js	✅	❌	✅	✅	N/A (file system)	✅ No crash
stress-test-fast.js	✅	✅	✅	❌	Synthetic memory	✅ No crash
stress-test-xlsx.js	✅	✅	✅	✅	Generated in memory	✅ No crash

Critical Finding

Synthetic stress tests do NOT crash, even with:

• Worker thread + uWS + pg + xlsx parsing
• 10 files × 5,000 rows × individual SELECT/INSERT queries
• Same memory allocation patterns

Only real multipart uploads via uWS.getParts() crash.

This strongly suggests the issue is specifically with buffer memory management in uWS.getParts() when:

1. Running in a worker thread
2. On macOS 26
3. With another native module (pg) in the same process
4. During heavy async operations

---

Intermediate Error Observed

Before full SIGSEGV, we sometimes caught:

Error: EFAULT: bad address in system call argument, write
    at Object.writeSync (node:fs:934:3)

This occurred when trying to access/copy buffers returned by uWS.getParts(). The EFAULT indicates the buffer memory became invalid during async operations.

We tried deep-copying buffers immediately:

const parts = uWS.getParts(buffer, contentType)
const files = parts.map(p => ({
    filename: p.filename,
    data: Buffer.from(p.data).slice() // Deep copy
}))

This did NOT prevent the crash - only delayed it by one file.

---

Minimal Reproducer

// CRASHES - real multipart upload in worker thread
import { Worker, isMainThread, parentPort } from 'worker_threads'

if (isMainThread) {
    const worker = new Worker(import.meta.filename)
    worker.on('exit', (code) => {
        if (code === 139) console.log('SEGFAULT!')
    })
} else {
    const uWS = (await import('uWebSockets.js')).default
    const pg = (await import('pg')).default
    const XLSX = (await import('xlsx')).default
    
    const pool = new pg.Pool({ connectionString: 'postgresql://...', max: 20 })
    
    uWS.App()
        .post('/upload', async (res, req) => {
            const contentType = req.getHeader('content-type')
            let buffer = Buffer.alloc(0)
            
            res.onData((ab, isLast) => {
                buffer = Buffer.concat([buffer, Buffer.from(ab)])
                if (isLast) {
                    // KEY: buffers from getParts() become invalid during async ops
                    const parts = uWS.getParts(buffer, contentType)
                    
                    for (const part of parts.filter(p => p.filename?.endsWith('.xlsx'))) {
                        // Parse xlsx from getParts() buffer
                        const workbook = XLSX.read(part.data, { type: 'buffer' })
                        const rows = XLSX.utils.sheet_to_json(workbook.Sheets[workbook.SheetNames[0]])
                        
                        // Heavy async DB work
                        for (const chunk of chunkArray(rows, 50)) {
                            await Promise.all(chunk.map(row => 
                                pool.query('INSERT INTO test VALUES ($1)', [JSON.stringify(row)])
                            ))
                        }
                        // CRASH after first file, before/during second file
                    }
                    res.end('done')
                }
            })
        })
        .listen(9999)
}

To reproduce: Upload 2+ xlsx files (any size, even small ones should work if pattern is similar) via multipart form-data to this endpoint on macOS 26.

---

What Works (No Crash)

// NO CRASH - same code in main thread (no worker)
const uWS = (await import('uWebSockets.js')).default
const pg = (await import('pg')).default
const XLSX = (await import('xlsx')).default

// ... exact same upload/parse/insert code
// Successfully processes all 10 files, 500K rows

---

Summary of Root Cause

The crash requires this specific combination:

1. ✅ Worker thread (main thread works fine)
2. ✅ uWS.getParts() multipart parsing (generated buffers don't crash)
3. ✅ Another native module (pg) in same worker
4. ✅ macOS 26 (macOS 15 works fine)
5. ✅ Heavy async operations on getParts() buffers

Hypothesis: uWS.getParts() returns buffers that reference internal uWS memory. When running in a worker thread on macOS 26, this memory becomes invalid/corrupted during async operations (possibly related to GC, event loop, or thread-local storage differences in macOS 26).

---

Request

1. Could you test uWS.getParts() in a worker thread on macOS 26?
2. Is there any known issue with buffer lifetime from getParts() in worker threads?
3. Would you be willing to compile with AddressSanitizer to help pinpoint the memory issue?

We're happy to provide any additional debugging assistance or test builds.

[pavel-nekrasov1]

Hi @uNetworkingAB ,

We've done extensive debugging and found a workaround. Here's what we learned:

Summary

Buffers returned by uWS.getParts() become corrupted during heavy async operations on macOS 26. This manifests as:

• SIGSEGV (exit 139) when accessing file data
• EFAULT: bad address in system call argument errors
• Corrupted data (e.g., Excel files failing ZIP signature validation)

Key Finding

The crash is NOT related to worker threads. We tested:

Configuration	Result
Worker thread + uWS + pg + xlsx	❌ Crash
Main thread + uWS + pg + xlsx	❌ Still crashes
Deep-copy buffers from getParts()	❌ Still crashes
Create new JS objects from getParts()	❌ Still crashes
Save files to disk immediately, read back later	✅ Works

The Pattern

// This crashes on macOS 26:
const parts = uWS.getParts(buffer, contentType)
for (const file of parts) {
    // File 1 processes fine
    const workbook = XLSX.read(file.data, { type: 'buffer' })  
    await heavyDbOperations(workbook)
    // File 2 - crash or corrupted data here
}

// This works:
const parts = uWS.getParts(buffer, contentType)
// Save ALL files to disk IMMEDIATELY (sync)
const savedFiles = parts.map(p => {
    const path = `/tmp/${uuid()}.xlsx`
    fs.writeFileSync(path, Buffer.from(p.data))
    return { ...p, path }
})
// Now process from disk
for (const file of savedFiles) {
    const buffer = fs.readFileSync(file.path)  // Safe!
    // ... process
}

Our Hypothesis

Something about how uWS.getParts() manages memory on macOS 26 causes buffers to become invalid during:

• V8 garbage collection cycles
• Heavy memory allocation (xlsx parsing)
• Concurrent async operations (database queries)

Even deep-copying with Buffer.from(part.data).slice() doesn't help - suggesting the corruption happens before or during the copy operation.

Workaround

Write all uploaded files to disk synchronously before any async processing. This completely bypasses the buffer lifetime issue.

Resolution

We've implemented the workaround in our codebase and the issue is resolved for us. Feel free to close this issue if you consider it outside the scope of uWebSockets.js, or keep it open if you'd like to investigate the macOS 26 memory behavior.

Thank you for your time looking at this!

---

Environment reminder:

• macOS 26.1 (Tahoe) - Apple Silicon
• Node.js v20.19.x
• uWebSockets.js v20.51.0 / v20.56.0
• Other native module: pg (PostgreSQL)

[uNetworkingAB]

This kind of "engineering" is child's play. Either you properly debug the issue with AddressSanitizer and fix it (that involves me potentially fixing the broken part of uWS from your dump), or you basically do finger paint engineering. Because this kind of arbitrary hacky "fix" is not a fix. None of this is how native code works - either is is correct and then it doesn't randomly segfault or it is entirely broken for this use. Only AddressSanitizer can nail it prooperly (given Valgrind is not available for macOS).

I am planning to start releasing binaries with AddressSanitizer built-in so that people like you can easily report proper issues with proper data for these kinds of issues. Because currently, this issue report is literal finger painting by 5 year olds. Sorry not sorry.

[uNetworkingAB]

Why don't you replace uWS.getParts with any other multipart parser?

[uNetworkingAB]

uWebSockets.js/src/addon.cpp

Line 77 in 6499438

Local<ArrayBuffer> partArrayBuffer = ArrayBuffer_New(isolate, (void *) part.data(), part.length());

This line should be ArrayBuffer_NewCopy. That's the issue. You have dead references.

[uNetworkingAB]

You can try the fixed binaries:

npm install uNetworking/uWebSockets.js#binaries