nbclassic 1.3.2 compatibility issue: dependency specification allows breaking changes in notebook 6.x

[hanbin8269]

Description

nbclassic 1.3.2 (released 2025-09-05) introduced breaking changes that cause compatibility issues with applications depending on the notebook package. The current dependency specification nbclassic>=0.4.7 allows automatic upgrades to this incompatible version, breaking production deployments and CI/CD pipelines.

The issue stems from notebook package's dependency specification using only a lower bound (>=) without an upper bound, allowing nbclassic to automatically upgrade to versions that introduce breaking changes.

Reproduce

1. Install notebook package in a fresh environment after 2025-09-05
2. The package manager automatically installs nbclassic 1.3.2 due to nbclassic>=0.4.7 specification
3. Run applications that worked with previous nbclassic versions
4. Experience compatibility issues/errors

Timeline Evidence:

• Build performed on 2025-09-04 (before nbclassic 1.3.2 release): ✅ Works correctly
• Build performed on 2025-09-10 (after nbclassic 1.3.2 release): ❌ Encounters errors

Diagnosis:
The issue was diagnosed by comparing build timestamps with nbclassic release dates and identifying that the breaking change coincided with the nbclassic 1.3.2 release on 2025-09-05.

Expected behavior

The notebook package should either:

1. Pin nbclassic to a specific working version (e.g., nbclassic==1.3.1)
2. Use a version range with upper bounds (e.g., nbclassic>=0.4.7,<1.4.0)
3. Ensure backward compatibility is maintained in nbclassic releases

This would prevent automatic upgrades to incompatible versions while still allowing security and bug fixes.

Context

• Operating System and version: Linux (production environment)
• Browser and version: N/A (server-side issue)
• Jupyter Notebook version: Multiple versions affected that depend on nbclassic

Additional Context:

• This issue affects production deployments and CI/CD pipelines
• The problem was resolved temporarily by explicitly pinning nbclassic version in requirements
• Related to community decision in PR Depend on nbclassic 0.4.7 #6593 where strict pinning was changed to lower bound only
• The issue demonstrates why dependency version ranges need upper bounds for stability

Root Cause:
Jupyter community previously decided to use nbclassic>=0.4.7 instead of exact pinning after community feedback about distribution packaging. However, this decision didn't account for potential breaking changes in minor/patch releases.

Proposed Solution:
Update the dependency specification to include an upper bound that excludes the problematic version:

dependencies = [
    "nbclassic>=0.4.7,<1.4.0",  # or pin to specific version
    # ... other dependencies
]

Troubleshoot Output

# This would be filled when actually running the command
# jupyter troubleshoot output would go here

Command Line Output

# This would be filled when actually running the command
# jupyter notebook --debug output would go here showing the specific errors

Browser Output

# Not applicable for this server-side dependency issue
# But if there are browser-side errors, they would go here

[krassowski]

nbclassic 1.3.2 (released 2025-09-05) introduced breaking changes that cause compatibility issues with applications depending on the notebook package.

What breaking changes did it introduce? What is not working?

[krassowski]

@hanbin8269 as one data point, https://github.com/jupyter/nbclassic/releases/tag/v1.3.2 does not list any breaking changes; rather than changing the pin, the desirable solution would be to fix whatever is broken (if anything)

[hanbin8269]

You're absolutely right that we should fix the underlying problem rather than just pinning the version. I completely agree.

Let me provide more detailed information about what we're observing.
When nbclassic 1.3.2 is installed in notebook 6.x environments, the static files /static/components/es6-promise/promise.min.js, /static/components/react/react.production.min.js, and /static/components/react/react-dom.production.min.js return 404 errors,

causing the notebook interface to render as a blank screen when launching with ipykernel.

Our builds worked until September 4th and began failing after September 5th when nbclassic 1.3.2 was released

[krassowski]

Do you customize the page.html template?

It looks this is related to jupyter/nbclassic#363 and similar changes. Maybe shims (symbolic links?) could be added for the old file paths?

[krassowski]

I see there is work in progress here: jupyter/nbclassic#375 and this issue is a duplicate of jupyter/nbclassic#372

[hanbin8269]

Thank you for your confirmation. I will close this issue.