Imagine handing a laptop to a new employee with all company files available out of the box and continuously synced — a pretty cool feat, right?

Sure, if only configuring the policies wasn’t an administrative nightmare.

We were developing VisualDrive Server, a self-hosted server for OneDrive. And we tried to make the automount experience a bit more intuitive.

Err… what? Automount?​

Automount is a shorthand for the “Configure team site libraries to sync automatically” OneDrive policy.

The OneDrive client app has many policies that can be configured by the administrator. They change different aspects of the app behavior. For example, you can configure silent sign-in, customize bandwidth usage, back up standard folders, and automatically mount folders.

An automount policy allows predefined shared locations to automatically sync to your device. These locations appear as folders in the File Explorer. Different users can have different automount policies assigned to them.

Why is cloud automount hard to configure?​

In the cloud, the server environment and the OneDrive policy distribution environment have no knowledge of each other.

As a result, no administrative tool can provide a convenient editor for the automount configuration — one that stays up-to-date with the remote state, and where you can pick what to mount.

This results in a rather unintuitive configuration experience with several problems:

Problem 1: Getting the library ID​

To mount a library, you need its ID. But there’s no admin interface for this. Instead, you have to navigate to the library in a browser and start syncing it to your device. On the sync dialog, you have the Copy library ID link:

However:

• To sync, you need read access. Most administrators that I know aren’t eager to grant themselves unnecessary permissions.
• The copy link may be missing. If so, the recommended way is to grab the ID from the browser Developer Tools.
• You may need to manually unescape the ID. The docs casually say that you should run [uri]::UnescapeDataString("Copied String").

Problem 2: Editing policies without context​

Once you have the ID, it’s time to configure the Group Policies. An ID value looks like this:

tenantId=b456fb95‑9415‑4f96‑b039‑0f9fba5fea39&siteId={7852d54e‑97c2‑4cea‑9ab8‑2abf9e51c41a}&webId={60e7dfb7‑aa75‑44ea‑bd61‑2f65f3dfb0fb}&listId={B81F17DE‑CA10‑4BF6‑8611‑458960EDFA20}&webUrl=https%3A%2F%2Fexample%2sharepoint%2com%2Fsites%2FOffice%5FTemplates&version=1

So here is the typical editing experience for those policies:

Standard policy editors are unaware of your actual intent (to mount a specific server object). And with long opaque IDs, a name-value table can quickly become unmaintainable, even if you introduce a sophisticated naming scheme.

For example, how do you know if a half-year-old configuration still points to an existing object on the server? Or check if any entries have outdated names?

Problem 3: The eight-hour delay​

Let’s say you configured the policy and want to test it.

Well, you can’t :)

At least, not immediately. Automount happens with a non-configurable delay of up to 8 hours. So, you either have to be very patient or deploy straight to production, embracing cowboy administration style.

Could Microsoft do better? It’s hard to say. Perhaps a few tweaks could improve the situation:

• Using base64url in the IDs would eliminate the need for manual encoding.
• Embedding additional metadata into the IDs could help present them more clearly in the user interface.
• A configurable delay interval would allow for easier testing and deployment.

But these improvements would still be marginal because the core problem remains: the policy distribution environment has no knowledge¹ about the server. You still can’t pick objects from the server or perform common actions (like checking if the configuration is correct).

Much easier in a self-hosted environment​

There’s a saying: solving a hard engineering problem often requires changing the requirements or flipping a core decision axis.

In our case, VisualDrive Server already is on an entirely different axis because it’s self-hosted.

Essentially, it combines the server and the policy distribution environments into one. All administration happens through a single management console. The console configures the server itself and all OneDrive policies in the form of Group Policy objects. We did have to write a full-featured Group Policy editor just for that:

Because we control both environments, sharing state between them becomes an ordinary technical task. And suddenly, all of the original problems have simple solutions:

Passing the state around​

While sharing state should be an ordinary technical task, our architecture made it slightly peculiar.

VisualDrive Server uses what we call a macroservice architecture. The core service (vdrivesvc.exe) encloses all of the state. All background and regular operations run as embedded pseudo-services within vdrivesvc.

The biggest advantage of this model is exclusive access to the internal database. With a macroservice, every internal component accesses the content directly without any inter-process communication (IPC).

The obvious downside is reduced isolation: a crash anywhere within the service takes everything down.

The far less obvious downside is the development inertia. When everything folds into one single service, you start to actively resist adding external endpoints. Why bother building an IPC infrastructure when you can add another pseudo-service?

Unfortunately, this concept has its limits.

To configure the automount policies, the management console (vdrivemgr) needs to know about the items on the server. And you cannot fold the entire console into a background service.

So, we had to shave the yak and finally implement an actual IPC infrastructure. Under the hood, it is nothing out of the ordinary. We use a named pipe with an appropriate security descriptor. The client (management console) and the server communicate by exchanging JSON messages:

Result: a better automount experience​

Thanks to our self-hostedness², we were able to expose the server state to the management console and provide a much more intuitive experience for the automount configuration.

It consists of three parts:

Together, this results in a standard, even a bit boring Windows administrative experience. Seeing it for the first time, you might wonder what the big deal is. Unless you know or have used the alternative, of course.

In our case, the goal was building VisualDock Server with the help of Visual Studio (the original one, not VS Code). VisualDock relies on Moby. Moby is written in Go. But Visual Studio doesn’t support Go.

Where’s our yak?​

Most of VisualDock Server is written in C#, with a lot of MSBuild magic happening behind the scenes. This makes using Visual Studio a pretty natural choice.

However, Visual Studio is like a limousine. If you do .NET and C++ development, occasionally throwing in some TypeScript, you get a lavish ride from point A to B. But if you want to go slightly off-road, you gotta do something about that suspension beforehand².

Go isn’t the usual guest in Visual Studio, and the only thing offered out of the box is the TextMate-based syntax highlighting. So, for a proper development experience, you need to keep two different IDEs and switch back and forth between them. The cost of that tends to stack up, especially when aiming for a coherent development environment across the team.

“Wouldn’t it help if we built an extension with a minimal Go integration for Visual Studio?”

Surely, that would help. We have experience in developing VS extensions, which would likely make it a weekend-size task. But isn’t that a massive detour from building the actual product?

Maybe this yak is different?​

There’s the yak: you need a Go integration plugin, which will help you work with a subcomponent written in Go, which is responsible for a significant part of your business logic, which is needed to build your final product.

Conventional wisdom says that if you find yourself with a dependency chain this long, you need to cut it, find an alternative or a compromise.

But… there are benefits in unifying the development environment, and, as it happened, we were in the right mood to give it a try.

How did we shave the yak?​

We decided to make a simple Go integration extension for Visual Studio.

Visual Studio offers decent Language Server Protocol (LSP) support. So, building a language integration extension is mostly about properly wiring things up and deciding on the feature set.

In case of Go, the standard language server is Gopls, and it’s offered by the core language team. We just had to teach it to speak with Visual Studio.

Surprisingly, the actual implementation is rather uninteresting to write about. But we learnt a few things along the way, and they seem to be worth mentioning:

1. Empty VSIX extension project: 2026 edition​

Pretty much everyone in the .NET ecosystem has moved to so-called SDK-style projects. These can be identified by the <Project Sdk="..."> preamble.

A VSIX package is the standard way to bundle and distribute Visual Studio extensions. For a long time, the default VSIX project template in Visual Studio wasn’t using the SDK-style, but it seems there is finally an official way to do it.

The trick is to reference the Microsoft.VisualStudio.Sdk.Build SDK and specify a custom TargetFramework, like vs17.12. Here is a quick snippet of what that modern project file looks like:

<Project Sdk="Microsoft.VisualStudio.Sdk.Build">
  <PropertyGroup>
    <RootNamespace>VsGo</RootNamespace>
    <AssemblyName>VsGo</AssemblyName>
    <AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
    <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
    <TargetFramework>vs17.12</TargetFramework>
    <Platforms>AnyCPU</Platforms>
  </PropertyGroup>
  <PropertyGroup>
    <GeneratePkgDefFile>true</GeneratePkgDefFile>
    <UseCodebase>true</UseCodebase>
    <IncludeAssemblyInVSIXContainer>true</IncludeAssemblyInVSIXContainer>
    <IncludeDebugSymbolsInVSIXContainer>false</IncludeDebugSymbolsInVSIXContainer>
    <IncludeDebugSymbolsInLocalVSIXDeployment>false</IncludeDebugSymbolsInLocalVSIXDeployment>
    <CopyBuildOutputToOutputDirectory>true</CopyBuildOutputToOutputDirectory>
    <CopyOutputSymbolsToOutputDirectory>true</CopyOutputSymbolsToOutputDirectory>
    <StartAction>Program</StartAction>
    <StartProgram Condition="'$(DevEnvDir)' != ''">$(DevEnvDir)devenv.exe</StartProgram>
    <StartArguments>/rootsuffix Exp</StartArguments>
  </PropertyGroup>
  …
</Project>

2. Unified settings are the new way to go​

Occasionally, Visual Studio picks up a thing or two from VS Code. This time, it comes in the form of the updated Unified settings:

Extension writers are pretty much forced to use them, because sticking to the older pattern will cause your extension to be labeled “Legacy” in the Settings window.

We still have some work to do here, because implementing these new settings is currently undocumented. Hoping to post on this topic soon.

3. Visual Studio cuts some corners in its LSP implementation​

In the LSP protocol, the client (Visual Studio) provides the server (Gopls) with different configuration settings. The synchronization model is twofold:

• The client can send the workspace.didChangeConfiguration request to notify the server that the settings have changed.

• The server can fetch the configuration settings it needs from the client with the help of the workspace.configuration request.

Unfortunately, the Visual Studio LSP client doesn’t implement the pull part of this model, and doesn’t support workspace.configuration requests. This results in Gopls not picking up some of the configuration settings.

We filed an issue for this, and hope that it will get fixed at some point.

The shaved yak 🐂​

In its current form, our extension provides context-aware syntax highlighting, code completion, the ability to navigate to definitions, find references, and rename things:

It isn’t eye-catching, but gets the work done. A couple of things are still on the roadmap.

Was it worth it?​

Contrary to the title, we chose to shave the yak and build an extension to manage all our code from one IDE.

There is some controversy around whether yak shaving is a good thing. Opponents say that it indicates a long dependency chain that can be avoided entirely by making better decisions. In this case, some of the decisions (e.g., using Moby) are unavoidable, thus making the argument less applicable.

Overall, there are both good and bad aspects. Maybe it’s too early for a retrospective, but the benefits seem to outweigh the drawbacks:

The bads​

• It was a distraction from the main project.
• It consumed some time and may be viewed as a form of procrastination.
• It may continue siphoning time for future maintenance, such as adding debugging support.

The goods​

• It was a distraction from the main project :)
• Being able to work with all your code in one IDE is a fairly important thing, with the benefits accumulating over time.
• We built something that might be useful to other developers, learning a thing or two along the way.
• I finally get to reference the legendary xkcd comic:

Oh, the restore operation needs to be durable?

I guess we’ll need to call FlushFileBuffers before closing the file. Or perhaps even use FILE_FLAG_WRITE_THROUGH so all our write operations go straight to disk. Flushing and writing through aren’t cheap, but we’re still talking about a single file.

…

Did you just say a million files?

Part 1: Denial​

A million files sounds inadequate, right?​

It might be reasonable to assume you won’t regularly have a million or more files in one location on Windows. That many files quickly becomes a burden for both the filesystem and the administrator when they have to perform maintenance tasks. Native Windows applications usually design their storage in ways that rarely produce millions of files².

Unfortunately, this doesn’t pass the reality check.

We were planning a backup feature for VisualSVN Server that had to be fully compatible with all existing Subversion repository formats. Older repository formats did not support packing that reduces the number of files on disk by repacking individual revision files together. So for a repository with a million commits you would have roughly 2 million files on disk.

Is there a reason to make restores durable?​

In other words, why even bother with restore durability?

The problem is that a non-durable restore is like an uncommitted transaction. You created some directories, wrote some files and indicated that your operation is complete. Then your server has a hard restart, and suddenly some of those directories are missing file entries and some of those files have zeroes in them or wrong metadata.

So before you indicate success and leave the scope of your operation, you have to go the extra mile to ensure that the data you wrote actually hit the disk — and will remain consistent in the event of a hard reboot or a BSOD.

How does one do that? By making things slower and flushing to disk.

Part 2: Anger​

Flushing to disk can’t be that slow!​

Actually, it is ridiculously slow, even on modern hardware.

When you call an API to write something to disk, the OS copies the data and will happily confirm the write request without waiting for the data to reach the disk. This improves latency and throughput.

But if you want to guarantee that the written data has reached the disk, you can ask the OS to FlushFileBuffers. This breaks the entire asynchronous pipeline and causes the OS to block until the data is written to disk and hardware flushed.

Those costs stack up quickly if you have to do that for every file. For writing a million files, expect a 5-10× slowdown in wall-clock time. It does get worse with HDDs.

If we were on Linux, all that surely would be much faster​

No, not really.

Unix I/O calls are generally faster due to reasons like not having tens of filesystem filters. But there is no silver bullet when it comes to flushing to disk, because you actually need to go all the way and make sure that the data is physically on the device.

There is some variety in things like fsync, fdatasync, F_FULLFSYNC, F_BARRIERFSYNC, so you actually may make your app faster by persisting less. But if we’re talking about similar guarantee levels, then the overall speed is pretty much the same.

Part 3: Bargaining​

So, apparently both the speed and durability are equally important for restoring a repository from backup.

You don’t want a restore to take hours, since that is going to hinder your disaster recovery strategy. But neither do you want to risk having a repository with a hidden corruption if you remotely called Restore-SvnRepository in PowerShell and didn’t notice that the VM got abruptly powered off.

How do we approach this problem if we want to retain both speed and durability?

Maybe we write through?​

Let’s say instead of calling FlushFileBuffers for every file, we open the files with FILE_FLAG_WRITE_THROUGH. It could be faster because the OS knows we want the durable writes for a file and has more opportunities to optimize the actual I/O.

Unfortunately, it doesn’t solve the speed problem for a million files. Even though we started writing directly to disk, the OS is still forced to complete a physical flush per every WriteFile. So each file becomes an unavoidable barrier in the terms of writing to the device. If most of the files are small, writing through doesn’t really help.

Maybe we restore multiple files at once?​

Building on the previous idea, we could make most of our I/O asynchronous, and restore multiple files at once. Theoretically, if we have N outgoing FlushFileBuffers calls or write-through operations, we can possibly expect an up to N times speedup.

In practice, the idea doesn’t work:

• The speedup is not so great. Perhaps, because we didn’t entirely remove flushing, but just queued as many operations as possible and expect the OS to magically coalesce them.
• In the actual case, there are both files and directories, which results in additional dependencies that limit how many operations you can queue.
• Asynchronously calling FlushFileBuffers is tough.
• Juggling with a lot of open file handles is also tough and error-prone.
• That makes the restore code asynchronous, thus far less predictable and more complex.

Maybe we restore straight into a packed form?​

We could try reassembling content on-the-fly when restoring, so that our million of files would be restored as a much lower number of packed files. Then flushing them to disk is no longer a problem.

A nice concept, but it’s impractical for multiple reasons:

• Restore cannot result in data that is different from what has been backed up. Otherwise, you’ve just lost the level of protection backup was supposed to give and turned your performance problem into a much more high-level problem.

• If for some reason your backup was taken from a corrupted repository, with repacking it on-the-fly, you may not be able to restore it at all.

• Repacking requires random access to files in a repository, so that would require building a fairly complex VFS that works over incremental backup snapshots.

Maybe we flush the whole volume?​

Documentation for FlushFileBuffers says the following:

To flush all open files on a volume, call FlushFileBuffers with a handle to the volume. The caller must have administrative privileges.

While we don’t really want all open files, we’re looking for a way to ensure that the content of all our cached files hits the device. Luckily, the DDK docs for NtFlushBuffersFileEx say exactly that:

//  If a volume handle is specified:
//      - Write all modified data for all files on the volume from the
//        Windows in-memory cache.
//      - Commit all pending metadata changes for all files on the volume
//        from the Windows in-memory cache.
//      - Send a SYNC command to the underlying storage device to commit
//        all written data in the devices cache to persistent storage.

Theoretically, if we accompanied every restore with a full volume flush, that would solve all problems. Flushing the volume doesn’t depend on the number of restored files. And it only introduces a single flush barrier to the whole operation, allowing all disk writes to happen asynchronously.

But the requirement for administrative privileges is a deal-breaker. In our case, the user may not have OS-level administrative privileges but should still be able to restore a repository from backup.

Part 4: Depression​

Doing the math makes the results look grim.

If you have two million files and each FlushFileBuffers takes just 2 milliseconds, that’s more than an hour just for the metadata and hardware synchronization. And that’s before we’ve even accounted for the actual data transfer.

With all known options exhausted, it’s time to accept…

…that we’re ready to start relying on undocumented internals.

Part 5: Acceptance​

Out of all the proposed solutions, only flushing the volume root seems to address the root cause of the problem and scale well. We accepted that we’re okay with undocumented behavior, but what can we really do if flushing the volume normally requires elevated privileges?

Microsoft has been always known for accurately keeping compatibility and porting undocumented features, so if there’s a hint, it would be in the code of the FAT filesystem driver. As it turns, when this driver handles IRP_MJ_FLUSH_BUFFERS, flushing the volume root directory does exactly the same as flushing the volume. But that doesn’t require special privileges!

Did this behavior find its way to NTFS and ReFS? Only one way to find out.

Going practical​

Below is a quick snippet we can use to open the mount point as a directory and flush it:

#define WIN32_LEAN_AND_MEAN
#include <Windows.h>

WCHAR volumePath[MAX_PATH];

// Resolve the volume mount point.
GetVolumePathName(filePath, volumePath, _countof(volumePath));

// Open the mount point as a directory with FILE_FLAG_BACKUP_SEMANTICS
// and OPEN_EXISTING flags.
// NtFlushBuffersFileEx() requires FILE_APPEND_DATA or FILE_WRITE_DATA
// so we try both of them.
HANDLE handle = CreateFile(
    volumePath,
    FILE_APPEND_DATA,
    FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
    NULL,
    OPEN_EXISTING,
    FILE_FLAG_BACKUP_SEMANTICS,
    NULL);

// Simplified error checking, better to check for ERROR_ACCESS_DENIED,
// ERROR_NETWORK_ACCESS_DENIED and ERROR_SHARING_VIOLATION.
if (handle == INVALID_HANDLE_VALUE)
{
    handle = CreateFile(
        volumePath,
        FILE_WRITE_DATA,
        FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
        NULL,
        OPEN_EXISTING,
        FILE_FLAG_BACKUP_SEMANTICS,
        NULL);
}

if (handle != INVALID_HANDLE_VALUE)
{
    FlushFileBuffers(handle);
    CloseHandle(handle);
}

Here is how this program behaves in Process Monitor:

So, that FlushFileBuffers call worked, and it took more than a second for the volume. It’s easy to confirm that the behavior mirrors a volume handle flush, and experiments also confirm that a physical flush is indeed triggered.

The conclusion: undocumented, but okay to use​

Sometimes it’s fine to go into a slightly undocumented territory.

Incorporating this trick into our restore implementation allowed us to make the whole operation durable without sacrificing performance. We replaced per-file flushing with a single (costly!) flush for the volume root, but got rid of the stacking costs and allowed our writes to be fully asynchronous.

In this case, examining the FAT driver code indicates that the undocumented behavior is not accidental. Since it’s shared by FAT, FAT32, NTFS and ReFS, we’d assume it is there to stay.

The scenario​

It is difficult to find a practical scenario where a single I/O call becomes the actual bottleneck of an entire operation. But for narrative purposes, it could be any of the following:

Then, at some point you discover that the runtime library you are using is calling GetFileInformationByHandle to answer those queries.

Maybe the library is relatively old and didn’t know any better at the time, or maybe it decided to transparently map the result of the API call. Regardless, this has doubled the number of required system calls, and forced them to retrieve more information than necessary.

How exactly did that happen?

Legacy of GetFileInformationByHandle​

The GetFileInformationByHandle populates a BY_HANDLE_FILE_INFORMATION structure with various information about the file:

struct BY_HANDLE_FILE_INFORMATION {
  DWORD    dwFileAttributes;
  FILETIME ftCreationTime;
  FILETIME ftLastAccessTime;
  FILETIME ftLastWriteTime;
  DWORD    dwVolumeSerialNumber;
  DWORD    nFileSizeHigh;
  DWORD    nFileSizeLow;
  DWORD    nNumberOfLinks;
  DWORD    nFileIndexHigh;
  DWORD    nFileIndexLow;
};

However, this structure is just a user-space facade. What we’re actually interested in is how this maps to the kernel representation of the same information, i.e., to the NT system calls.

From the structure definition, you might have noticed that the returned information falls into different categories. And from the standpoint of the NT API, the fields map to the following information classes:

Given that there are four different information classes, does filling the structure require four different syscalls? Let’s find that out.

Going practical​

Below is a quick snippet we can use to compare how those different calls behave, assuming we’re only interested in basic file information:

#define WIN32_LEAN_AND_MEAN
#include <Windows.h>

HANDLE file = CreateFile(
    L"test",
    FILE_ALL_ACCESS,
    FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE,
    NULL,
    OPEN_ALWAYS,
    0,
    NULL);

FILE_BASIC_INFO basicInfo = {0};
GetFileInformationByHandleEx(
    file,
    FileBasicInfo,
    &basicInfo,
    sizeof(basicInfo));

BY_HANDLE_FILE_INFORMATION byHandleInfo = {0};
GetFileInformationByHandle(file, &byHandleInfo);

Here is how this program behaves in Process Monitor:

So, while we didn’t get four separate syscalls, GetFileInformationByHandle still performed two syscalls instead of one:

• There is a special FileAllInformation class that was used to obtain all three necessary information categories (basic, standard and internal file information) in a single call to NtQueryFileInformation.

• But volume information is fully separated from file information, so the function also had to call NtQueryVolumeInformationFile.

Assuming our goal was simply to get the basic file metadata such as its timestamp, that extra call is just wasted CPU cycles and additional context switch overhead.

Connection with POSIX?​

While the way this API works can be explained by entirely legacy reasons, sometimes there are deeper connections to be found.

In this case, the BY_HANDLE_FILE_INFORMATION structure looks remarkably similar to POSIX struct stat, both containing the device (volume) ID, number of links, and inode (index) numbers:

struct stat {
    dev_t      st_dev;      /* ID of device containing file */
    ino_t      st_ino;      /* Inode number */
    mode_t     st_mode;     /* File type and mode */
    nlink_t    st_nlink;    /* Number of hard links */
    uid_t      st_uid;      /* User ID of owner */
    gid_t      st_gid;      /* Group ID of owner */
    dev_t      st_rdev;     /* Device ID (if special file) */
    off_t      st_size;     /* Total size, in bytes */
    blksize_t  st_blksize;  /* Block size for filesystem I/O */
    blkcnt_t   st_blocks;   /* Number of 512 B blocks allocated */

    struct timespec  st_atim;  /* Time of last access */
    struct timespec  st_mtim;  /* Time of last modification */
    struct timespec  st_ctim;  /* Time of last status change */
};

The conclusion: be specific​

This inefficiency can be fixed by using an API that maps with the underlying kernel primitive, requesting only the data you actually intend to consume:

• GetFileInformationByHandleEx with a specific information class, or
• GetFileSizeEx which is a convenient wrapper if you only need the file size.

By using the more specific APIs, you can cut the syscalls in half and remove the overhead of querying volume information.

Finally, beware of the odd-looking QueryInformationVolume Process Monitor entries for files. While they may not contribute to the overall performance of your application, they can indicate you’re inadvertently using the more costly version of the API.

We’ve been using Next.js in static export mode for our website. With the most recent upgrade to Next.js 16, one problem quickly manifested itself with multiple 404 requests showing up in the network inspector.

Prefetching RSC in Next.js​

If you have used Next.js, you may know that the <Link> component used for intra-site navigation will by default prefetch its target content when it’s within the viewport. What it fetches is called the React Server Component (RSC) payload, which contains a prerendered representation of the server component.

Prior to Next.js 16, a typical prefetch would ask for a single file:

In Next.js 16, the picture changes dramatically:

Now, what has really changed, except for the number of requests?

Next.js 16 has a new feature called Cache Components, and its implementation has overhauled how RSC is fetched, even if the feature is not used. In the new fetch structure, different segments are now fetched separately, comprised of parts like __next._tree.txt, __next._head.txt, and __next._index.txt.

The problem: 404 requests to RSC​

As you might have noticed, some of those requests now result in 404 errors. While those errors don’t crash the application, they effectively disable prefetching and degrade the user experience.

So what’s causing that? As it turns out, there is a mismatch between the on-disk generated files and the URL paths requested during the prefetch:

• The on-disk path is: __next/company/__PAGE__.txt (nested directories).
• The request path is: __next.company.__PAGE__.txt (dot-separated filename).

The root cause seems quite unremarkable, and there is an existing bug report upstream. Apparently, the path construction logic diverged between the client router and the build output on Windows.

The workaround: a build adapter​

Until the fix for the core issue arrives, the problem can be worked around.

The new segment cache still feels experimental, so why not tackle it with another experimental feature? Next.js 16 introduced build adapters, so let’s use one to rename the files and put them into their expected places.

Add this module somewhere in your source tree (e.g., build/adapter.js):

const fs = require("fs");
const path = require("path");

/** @type {import("next").NextAdapter} */
const adapter = {
    // https://github.com/vercel/next.js/issues/85374
    name: "fix-issue-85374",

    async onBuildComplete({ outputs }) {
        for (const file of outputs.staticFiles) {
            const sourcePath = file.filePath;
            const targetPath = fixupPath(sourcePath);
            if (targetPath) {
                await fs.promises.rename(sourcePath, targetPath);
            }
        }
    }
};

function fixupPath(filePath) {
    const components = filePath.split(path.sep);
    const idx = components.findIndex(x => x.startsWith("__next."));

    if (idx >= 0 && idx < components.length - 1) {
        // Flatten rest of the segments into single dot-separated name.
        const result = components.slice(0, idx);
        result.push(components.slice(idx).join("."));
        return result.join(path.sep);
    }
    else {
        return null;
    }
}

module.exports = adapter;

Then, reference it from your next.config.ts:

import { NextConfig } from "next";

const config: NextConfig = {
    output: "export",
    // … other configuration
    experimental: {
        adapterPath: require.resolve("./build/adapter.js"),
    }
};

This forces the nested file paths to become the flat, dot-separated filenames the client expects.