WordPress add_settings_error Example: Show Settings Feedback Correctly

Last reviewed: April 26, 2026

Settings pages feel unfinished when validation fails silently or success feedback is inconsistent. WordPress already provides a native message pipeline for this through add_settings_error() and settings_errors(), but many plugins still fall back to ad hoc notices or raw query-string flags.

This guide shows how to attach Settings API feedback to the actual sanitize flow so users see the right success, warning, or error message after a save.

Add feedback in the sanitize callback

<?php
register_setting(
	'vulnwp_general',
	'vulnwp_api_base_url',
	array(
		'sanitize_callback' => 'vulnwp_validate_api_base_url',
	)
);

function vulnwp_validate_api_base_url( $value ) {
	$value = esc_url_raw( $value );

	if ( '' === $value ) {
		add_settings_error(
			'vulnwp_api_base_url',
			'vulnwp_api_base_url_empty',
			'API base URL cannot be empty.',
			'error'
		);

		return get_option( 'vulnwp_api_base_url', '' );
	}

	add_settings_error(
		'vulnwp_api_base_url',
		'vulnwp_api_base_url_saved',
		'API base URL saved successfully.',
		'success'
	);

	return $value;
}

Putting the feedback inside the sanitize callback keeps the message tied to the actual validation outcome instead of guessing later whether the save should be considered valid.

Render the messages on the page

function vulnwp_render_settings_page() {
	?>
	<div class=\"wrap\">
		<h1>VulnWP Settings</h1>
		<?php settings_errors( 'vulnwp_api_base_url' ); ?>
		<form action=\"options.php\" method=\"post\">
			<?php
			settings_fields( 'vulnwp_general' );
			do_settings_sections( 'vulnwp_general' );
			submit_button();
			?>
		</form>
	</div>
	<?php
}

WordPress can display many setting messages automatically after submission, but explicit placement with settings_errors() keeps the page layout predictable.

Choose the right message type

Modern WordPress supports error, success, warning, and info. Use them deliberately instead of reporting everything as an error.

Production checklist

• Add feedback inside the sanitize callback for the relevant setting.
• Return a safe fallback value when validation fails.
• Render the messages with settings_errors() in a predictable location.
• Use message types that match the real outcome.
• Keep error codes stable so notices stay easy to trace.
• Avoid hand-rolled query-string success banners when the Settings API already covers the workflow.

Common mistakes

• Displaying generic success banners even when validation failed. That confuses operators immediately.
• Not returning a fallback value. Settings fields can end up blank unexpectedly.
• Mixing unrelated settings into the same error bucket. Messages should map cleanly to the field or group.
• Using custom admin notices for every Settings API save. Native settings feedback is already available.
• Skipping explicit rendering. Message placement becomes inconsistent across custom pages.

Related reading

If the setting itself is registered manually, pair this with the Settings API guide. If the saved value is a URL, combine it with the esc_url article so validation and storage rules stay aligned.

References and further reading

• WordPress Code Reference: add_settings_error()
• WordPress Code Reference: settings_errors()
• WordPress Plugin Handbook: Using Settings API