Sklearn NotFittedError — Fit Before Predict

Your training script ran clean, the model artifact is saved, and the API boots without complaint. Then the first real request lands and the traceback says it plainly: sklearn.exceptions.NotFittedError: This LogisticRegression instance is not fitted yet. NotFittedError is scikit-learn's guardrail against meaningless predictions. Every estimator separates configuration (the constructor) from learning (fit): until fit runs, there are no coefficients, no tree splits, no cluster centers — so predict has nothing to apply. The error fires the moment any method needing learned state — predict, predict_proba, score, transform — runs on an unfitted object. The loud failure beats a silent random prediction.

The confusion is that 'unfitted' rarely means 'you forgot fit entirely.' It usually means the wrong object got the predict call: a fresh instance shadowing the trained one, one pipeline step fitted outside its pipeline, a test set passed through fit_transform, or a pickle saved before fitting completed. Each variant names the same error but needs a different fix.

This guide covers all five: predicting before fitting, unfitted pipeline steps, the fit_transform-train versus transform-test split, never-fitted pickles, and check_is_fitted as your verification habit. You'll be able to read the error, name the ordering bug, and fix it in minutes.

What NotFittedError Guards Against

NotFittedError fires when a method needing learned state runs before fit creates it. Scikit-learn estimators store everything learned with a trailing underscore — coef_ on linear models, tree_ on trees, cluster_centers_ on KMeans, classes_ on classifiers. Until fit runs, those attributes don't exist, and predict raises instead of guessing. The message names the class and the remedy: This LogisticRegression instance is not fitted yet. Call 'fit' with appropriate arguments before using this estimator.

The design is deliberate. A prediction from an unfitted model isn't an error with a wrong answer — it's a random number wearing a model's uniform. Returning zeros or raising a warning would let garbage flow into dashboards, billing, and medical decisions silently. The loud exception forces the ordering bug into the open at the exact call site, with the exact class, every time.

Your first diagnostic is check_is_fitted from sklearn.utils.validation. It inspects the estimator for any fitted attribute and raises the same NotFittedError when none exists. Run it on the suspect object in isolation — not on the pipeline, not on a wrapper — to confirm unfitted state before theorizing. Then check vars(model): fitted estimators show their learned attributes plainly, while unfitted ones show only constructor parameters.

Note the scope: predict, predict_proba, predict_log_proba, decision_function, score, and transform all require fitted state. Only fit, fit_predict (on clustering), get_params, and set_params work unfitted — everything else is gated.

from sklearn.datasets import load_iris
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.utils.validation import check_is_fitted
from sklearn.exceptions import NotFittedError

X_train, X_test, y_train, y_test = train_test_split(
    *load_iris(return_X_y=True), test_size=0.2, random_state=0)

model = LogisticRegression(max_iter=1000)

try:
    check_is_fitted(model)
except NotFittedError as exc:
    print("unfitted:", exc)

# The fix: fit before predict.
model.fit(X_train, y_train)
check_is_fitted(model)  # now passes silently
print("test accuracy:", model.score(X_test, y_test))

Unfitted Steps Inside Pipelines and Grids

Pipelines chain preprocessing and modeling so one fit call trains every stage in order — but only when you fit the pipeline itself. Calling pipe.fit(X_train, y_train) runs each step's fit_transform in sequence and the final estimator's fit, threading outputs correctly. Predicting with pipe.predict then replays each step's transform. The moment you fit steps individually — scaler.fit here, classifier.fit there — you bypass the pipeline's routing and its fitted-state bookkeeping, and the pipeline still considers its steps unfitted.

ColumnTransformer has the same contract with an extra dimension: it fits one transformer per column group and concatenates the results. Fitting a sub-transformer manually and slotting it into a fresh ColumnTransformer leaves the parent unfitted, so transform raises even though the piece works standalone. The parent's fitted flag is what gates downstream calls, not the child's.

A subtler variant: cloning. GridSearchCV and cross_val_score clone the pipeline per fold and fit each clone — your original stays unfitted by design. Predicting with the pre-search object afterward throws, while best_estimator_ (refit on full data) works. This surprises teams who treat the searched object as trained.

Rule it simply: exactly one object gets fit — the outermost pipeline — and exactly that object predicts. Inspect pipe.named_steps after fitting to see every step carrying fitted attributes, and never reach inside to fit pieces.

from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split

X_train, X_test, y_train, y_test = train_test_split(
    *load_iris(return_X_y=True), test_size=0.2, random_state=0)

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
from sklearn.utils.validation import check_is_fitted

pipe = Pipeline([
    ("scaler", StandardScaler()),
    ("clf", LogisticRegression(max_iter=1000)),
])

# Wrong: fitting steps individually leaves the pipeline unfitted.
# pipe.named_steps["scaler"].fit(X_train)

# Right: fit the pipeline end to end.
pipe.fit(X_train, y_train)
check_is_fitted(pipe)  # passes silently when fitted
print(pipe.predict(X_test[:5]))

fit_transform on Train, transform on Test

The fit_transform versus transform split is where NotFittedError meets data leakage. fit_transform learns parameters from its input and applies them; transform only applies previously learned ones. Training data gets fit_transform (learn the scaler's mean from train, then scale train). Test data gets transform only (apply train's mean to test). Reversing this — transforming train with a scaler fitted on test, or fitting on the test set at all — leaks test statistics into training and produces validation scores that production can never reproduce.

The failure mode teams actually hit: a script calls scaler.fit_transform(X_test) or reuses one scaler across both sets in the wrong order, then a later refactor serves predictions through a path where the scaler was never fitted on anything. The error surfaces far from the cause — at predict time in serving — while the bug sits in preprocessing order during training.

Pipelines eliminate the whole class. When scaling lives inside a Pipeline evaluated with cross_val_score, each fold clones the pipeline and fits its own scaler on that fold's training split only. There is no shared scaler to misuse, no order to remember, and no leakage. The pipeline object is the single source of fitted state.

If you must scale manually, enforce the order with code structure: split first, then exactly one fit_transform call on train and transform calls on everything else. Grep for fit_transform in review — every call site should name a training split.

Never-Fitted Pickles and Version Skew

A fitted estimator only helps if the fitted object is what gets saved. The classic production NotFittedError comes from joblib.dump running on a fresh constructor — same class, same parameters, zero learned state — while fit ran on a different instance two cells up. Training metrics look great (computed from the fitted twin), the registry holds the unfitted twin, and serving throws on its first request.

Verify at both ends. After dumping, load the artifact in a fresh process and call check_is_fitted plus one golden prediction before publishing it. After loading in serving, call check_is_fitted again at startup and refuse to boot on failure. Two cheap checks bracket the entire export path and catch pre-fit saves, truncated files, and version-skewed unpickles alike.

Version skew deserves its own warning: pickles embed sklearn-version-specific structures, and unpickling across versions can warn, silently misbehave, or drop fitted state. Pin scikit-learn==x.y.z identically in training and serving requirements, record the version in sidecar metadata at export, and assert equality at load. Treat the pickle plus its version pin as one atomic artifact.

Prefer dumping whole pipelines over bare estimators. A pipeline pickle carries preprocessing and modeling state together, so serving can't reassemble mismatched pieces — the object that was validated in training is byte-for-byte the object that predicts.

import joblib
from sklearn.datasets import load_iris
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.utils.validation import check_is_fitted

X_train, X_test, y_train, y_test = train_test_split(
    *load_iris(return_X_y=True), test_size=0.2, random_state=0)
pipe = Pipeline([("scaler", StandardScaler()),
                 ("clf", LogisticRegression(max_iter=1000))])

# Export AFTER fit, from the SAME object that was fitted.
pipe.fit(X_train, y_train)
joblib.dump(pipe, "/tmp/model.joblib")

# Verify in a fresh process before publishing the artifact.
loaded = joblib.load("/tmp/model.joblib")
check_is_fitted(loaded)  # raises if the wrong object was saved
print("golden predictions:", loaded.predict(X_test[:3]))
print("test accuracy:", loaded.score(X_test, y_test))

check_is_fitted as a Startup Gate

check_is_fitted is a one-line function that should appear in three places: unit tests, export jobs, and service startup. In tests, assert fitted state after every training helper returns — it catches refactors that accidentally return fresh instances. In export jobs, gate publication on it — no fitted state, no registry upload. In serving, call it before binding the port — a container that can't predict shouldn't accept traffic.

The function accepts any estimator, pipeline, or meta-estimator and checks for fitted attributes (anything ending in _ plus a fitted flag where defined). Pass a message argument to brand the error with context: check_is_fitted(model, msg="startup: production fraud model"). When it raises in logs, you know exactly which object and which stage failed instead of decoding a bare traceback.

Pair it with feature validation for a complete startup gate. Fitted state proves the model learned; column checks prove today's input matches training's schema. Together they catch the two dominant serving failures — unfitted artifacts and schema drift — before either reaches a user. Both checks run in milliseconds against an in-memory object.

Make unfitted a deploy-blocking state, not a retryable request error. Retrying a predict against an unfitted model can never succeed — the fix is a new artifact, not patience. Alert the model pipeline, not the request path.

import joblib

from sklearn.utils.validation import check_is_fitted

def load_production_model(path):
    model = joblib.load(path)
    # Fail the deploy here, not the first user request.
    check_is_fitted(model, msg=f"startup: artifact at {path} is not fitted")
    expected = joblib.load(path.replace("model.joblib", "features.joblib"))
    return model, expected


def predict(model, expected_columns, X):
    missing = set(expected_columns) - set(X.columns)
    if missing:
        raise ValueError(f"schema drift, missing columns: {sorted(missing)}")
    return model.predict(X[expected_columns])

Prevent It Structurally: One Export Path

Long-term prevention is structural: make the unfitted state unrepresentable in your workflow. Keep exactly one training entrypoint that fits and exports the pipeline atomically — no notebook cells that can run out of order, no separate export scripts holding their own constructors. Parameterize it, version it, and run it in CI so the artifact is always built the same way.

Delete the patterns that breed wrong-object bugs. Ban bare estimator construction in serving code — serving loads artifacts, never constructors. Remove demo estimators and placeholder models from importable paths so no tired import can grab them. Review every fit_transform call site for the train-only rule, and prefer pipelines so the rule enforces itself.

Add contract tests around the artifact. A golden-sample test loads the production pickle and asserts exact predictions on a fixed input; it catches pre-fit saves, version skew, and feature-order changes in one assertion. A schema test asserts the serving feature list matches training's. Both run on every deploy, take seconds, and have saved more launches than any amount of careful notebook discipline.

Finally, pin and record everything: sklearn version, training date, data hash, feature list. Reproducibility turns the next NotFittedError from a mystery into a checklist — and checklists resolve in minutes.