From 790d7525f0138184c7c4709b0ebd3e4ff73f4ce5 Mon Sep 17 00:00:00 2001
From: Tomas Tomecek <ttomecek@redhat.com>
Date: Mon, 11 Jul 2016 10:28:19 +0200
Subject: [PATCH] document how to recover from api version mismatch

Signed-off-by: Tomas Tomecek <ttomecek@redhat.com>
---
 docs/api.md | 28 ++++++++++++++++++++++++++++
 mkdocs.yml  |  1 +
 2 files changed, 29 insertions(+)

diff --git a/docs/api.md b/docs/api.md
index 579057ae..738606d4 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -18,6 +18,34 @@ is hosted.
 * tls (bool or [TLSConfig](tls.md#TLSConfig)): Equivalent CLI options: `docker --tls ...`
 * user_agent (str): Set a custom user agent for requests to the server.
 
+
+## Version mismatch
+
+You may encounter an error like this:
+
+```text
+client is newer than server (client API version: 1.24, server API version: 1.23)
+```
+
+To fix this, you have to either supply exact version to `Client` which you know that server supports:
+
+```python
+client = docker.Client(version="1.23")
+```
+
+or let client pick the newest version server supports:
+
+```python
+client = docker.Client(version="auto")
+```
+
+or even
+
+```python
+client = docker.AutoVersionClient()
+```
+
+
 ****
 
 ## attach
diff --git a/mkdocs.yml b/mkdocs.yml
index 6cfaa543..abc68e54 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -7,6 +7,7 @@ theme: readthedocs
 pages:
 - Home: index.md
 - Client API: api.md
+- FAQ: faq.md
 - Port Bindings: port-bindings.md
 - Using Volumes: volumes.md
 - Using TLS: tls.md