Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Flutter HTTPS request fails with HandshakeException: CERTIFICATE_VERIFY_FAILED

ErrorHandshakeException: Handshake error in client (OS Error: CERTIFICATE_VERIFY_FAILED

Short answer

Dart refused the server's TLS certificate, so no request was sent. Check the server first: a missing intermediate certificate or a private CA are the usual reasons. Fix the chain or trust your own CA through a SecurityContext. Use badCertificateCallback only in debug builds, for one host.

  • Applies to Flutter 3.3x stable, Dart 3.x, package:http, dart:io HttpClient, OpenSSL 3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at what the server really sends, from a machine outside your app. The list of certificates and the verify result show whether the chain is complete.

    openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts
  2. 2Match what you see, then jump to its fix

    1. 1CERTIFICATE_VERIFY_FAILED against one public host, while other HTTPS hosts workThe server sends only its own certificate, not the intermediateFix
    2. 2CERTIFICATE_VERIFY_FAILED only against your staging or LAN hostA dev or internal server uses a self-signed or private-CA certificateFix
    3. 3It worked before and stopped on a date, or the date on the device or emulator is far from todayThe certificate is outside its validity periodFix
    4. 4The host is your own local or test server and you control itYou only need to get past it while developingFix

What does the error look like?

  • HandshakeException: Handshake error in client (OS Error: CERTIFICATE_VERIFY_FAILED
  • CERTIFICATE_VERIFY_FAILED while performing a POST request

Cause 1 of 4

The server sends only its own certificate, not the intermediate

1Check

Only one certificate appears in the -showcerts list. Let's Encrypt's own guidance says the most common reason a certificate validates on some platforms but not others is that the correct certificate chain was not provided.

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts

2Fix

Serve the full chain file (leaf plus intermediates) from the web server, not just the leaf file. The chain has to be complete for every client, not just for the one you tested with.

# nginx example
ssl_certificate     /etc/ssl/example/fullchain.pem;
ssl_certificate_key /etc/ssl/example/privkey.pem;

3Verify

Reload the server and request it from the app again; the HandshakeException no longer appears.

openssl s_client -connect api.example.com:443 -servername api.example.com -showcerts

Confirmed by letsencrypt.org

Did this fix it?

Cause 2 of 4

A dev or internal server uses a self-signed or private-CA certificate

1Check

Open the same URL on your computer and see who issued the certificate. If it is your own CA, the phone or Dart does not know that CA.

openssl s_client -connect staging.internal:443 -servername staging.internal </dev/null

2Fix

Make a SecurityContext that trusts the CA file you ship with the app and give it to HttpClient. Dart's docs say setTrustedCertificatesBytes adds a certificate to the trusted set for secure client connections.

import 'dart:io';
import 'package:flutter/services.dart';
import 'package:http/http.dart' as http;
import 'package:http/io_client.dart';

Future<http.Client> clientWithPrivateCa() async {
  final data = await rootBundle.load('assets/certs/internal-ca.pem');
  final context = SecurityContext(withTrustedRoots: true)
    ..setTrustedCertificatesBytes(data.buffer.asUint8List());
  return IOClient(HttpClient(context: context));
}

3Verify

Call the staging API with this client; no handshake error is thrown.

final client = await clientWithPrivateCa();
final res = await client.get(Uri.parse('https://staging.internal/health'));

Confirmed by api.dart.dev

Did this fix it?

Cause 3 of 4

The certificate is outside its validity period

1Check

RFC 5280 defines the validity period as notBefore through notAfter, inclusive. Print both dates from the server, and compare them with the date on the device.

echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -dates

2Fix

If notAfter is in the past, renew the certificate on the server. If the server dates are fine, correct the date and time on the emulator or phone.

# renew with your CA or ACME client, then reload the web server

3Verify

The notAfter date is in the future and the app connects.

echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null | openssl x509 -noout -enddate

Confirmed by rfc-editor.org

Did this fix it?

Cause 4 of 4

You only need to get past it while developing

1Check

Dart's badCertificateCallback runs when a server certificate cannot be verified; returning true accepts the connection. Treat it as a switch for debug builds and for one named host.

grep -rn 'badCertificateCallback' lib/

2Fix

Limit the bypass to debug mode and to one host. Never ship a callback that returns true for everything.

import 'package:flutter/foundation.dart';
import 'dart:io';

HttpClient devClient() {
  final c = HttpClient();
  c.badCertificateCallback = (cert, host, port) =>
      kDebugMode && host == 'dev.example.com';
  return c;
}

3Verify

A debug run reaches the dev host; a release build still rejects bad certificates.

flutter run --release

Confirmed by api.dart.dev

Did this fix it?

How do I stop it coming back?

  • Deploy the full-chain certificate file on every server, and test it with openssl s_client after each renewal.
  • Automate renewal and alert on notAfter dates well before they pass.
  • Ship private CA files as app assets and trust them through a SecurityContext, rather than turning verification off.
  • Never leave a badCertificateCallback that returns true in a release build.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.