Error: 'd3.layout is not a function' – Recovering from a Failed Upgrade

The Immediate Fix

The error d3.layout is not a function occurs because D3 v4 and later versions transitioned from a monolithic architecture to a modular one, completely removing the d3.layout namespace. To recover your visualization, you must map legacy d3.layout calls to their new top-level equivalents.

Common API Mappings

For most standard layouts, the fix is a direct replacement of the namespace:

• Pie Charts: Replace d3.layout.pie() with d3.pie().
• Tree Layouts: Replace d3.layout.tree() with d3.tree().
• Cluster Layouts: Replace d3.layout.cluster() with d3.cluster().

Complex Layout Changes

Some layouts underwent structural API changes and cannot be fixed with a simple find-and-replace. The most notable is the Force layout:

• Force Layouts: d3.layout.force() was replaced by d3.forceSimulation(). This is a fundamental shift from a layout object to a simulation-based API; you will likely need to update how forces (charge, center, link) are added to the simulation.
• Axes: While not in the layout namespace, d3.svg.axis() was also removed in favor of specific orientation functions like d3.axisBottom(), d3.axisLeft(), etc.

Implementation Strategy

To restore functionality without a full codebase rewrite, follow these steps:

1. Verify Version: Confirm the loaded version in the browser console using d3.version.
2. Namespace Update: Perform a global search and replace for d3.layout. to d3. for pie, tree, and cluster calls.
3. Simulation Refactor: Manually update d3.layout.force() calls to d3.forceSimulation() and adjust the force configuration.
4. Bundle Optimization: If bundle size is a constraint, transition from the full d3 bundle to specific ES6 modules (e.g., import {pie} from "d3-shape").

Assumptions and Constraints

This resolution assumes you are upgrading from v3 to v4 or higher. It is important to note that no official compatibility shim exists to restore the v3 API surface in newer versions. Attempting to load both v3 and v4 scripts simultaneously to avoid rewriting code will cause global namespace collisions and runtime instability.

Diagnostic Requirement

To provide a more precise migration path for the force layout, please specify if you are using d3.layout.force for a static one-time calculation or a dynamic, animated simulation.