How Should a Program Handle an Unsupported Feature?
From the earlier reference collection. Read the current software blog.
When an operation is unsupported, return a clear error that names the request and points to a valid alternative or documented limitation.
Detect the unsupported request early
A program may receive a validly formed request for a feature it does not implement. This is different from malformed input: the request can be syntactically correct while asking for an unavailable operation. Detect that condition near the boundary where capabilities are known, before performing unrelated work or changing state.
For example, a file converter might support text and image inputs but not audio. It should identify the requested audio conversion as unsupported instead of treating the file as empty or returning a generic success response.
Say what failed and why
A useful error identifies the operation or feature that cannot be handled, and gives enough context to distinguish it from a missing file, permission failure, or invalid parameter. Keep the message factual. Do not claim the feature is planned unless there is a reliable commitment to that effect.
Where the program has an error code or structured response format, use a stable code for callers and a human-readable explanation for people. Scripts can then respond predictably without parsing prose, while users can understand the immediate problem.
Offer an available next step
If a supported alternative exists, state it specifically. The converter could say that audio input is unsupported and point to the accepted formats, or suggest a separate preparation step if that step is genuinely part of the documented workflow. Do not recommend a feature or command that the program does not provide.
A command-line tool might return a nonzero status and print a short explanation to standard error. An API might return a documented error object. The exact form depends on the interface, but the result should be consistent and should not look like a successful operation.
Test the boundary behavior
Add a test that sends a well-formed but unsupported request and checks both the error category and the absence of unintended side effects. Also test a nearby supported request so future changes do not reject too much. Error messages can evolve, so tests should usually assert stable codes or key details rather than every punctuation mark.
Clear unsupported-feature handling preserves user trust: people can tell what the program did not do and what they can try next. When support later arrives, update the capability documentation and tests together so the advertised set of operations matches the implementation.