diff --git a/src/test/java/org/elasticsearch/test/rest/spec/RestApiParser.java b/src/test/java/org/elasticsearch/test/rest/spec/RestApiParser.java
index 722a5341764..2c3dc452f94 100644
--- a/src/test/java/org/elasticsearch/test/rest/spec/RestApiParser.java
+++ b/src/test/java/org/elasticsearch/test/rest/spec/RestApiParser.java
@@ -65,7 +65,9 @@ public class RestApiParser {
                                 while (parser.nextToken() == XContentParser.Token.FIELD_NAME) {
                                     restApi.addPathPart(parser.currentName());
                                     parser.nextToken();
-                                    assert parser.currentToken() == XContentParser.Token.START_OBJECT;
+                                    if (parser.currentToken() != XContentParser.Token.START_OBJECT) {
+                                        throw new IOException("Expected parts field in rest api definition to contain an object");
+                                    }
                                     parser.skipChildren();
                                 }
                             }
@@ -74,7 +76,9 @@ public class RestApiParser {
                                 while (parser.nextToken() == XContentParser.Token.FIELD_NAME) {
                                     restApi.addParam(parser.currentName());
                                     parser.nextToken();
-                                    assert parser.currentToken() == XContentParser.Token.START_OBJECT;
+                                    if (parser.currentToken() != XContentParser.Token.START_OBJECT) {
+                                        throw new IOException("Expected params field in rest api definition to contain an object");
+                                    }
                                     parser.skipChildren();
                                 }
                             }
diff --git a/src/test/java/org/elasticsearch/test/rest/test/RestApiParserFailingTests.java b/src/test/java/org/elasticsearch/test/rest/test/RestApiParserFailingTests.java
new file mode 100644
index 00000000000..c86660f5c81
--- /dev/null
+++ b/src/test/java/org/elasticsearch/test/rest/test/RestApiParserFailingTests.java
@@ -0,0 +1,97 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.elasticsearch.test.rest.test;
+
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.common.xcontent.json.JsonXContent;
+import org.elasticsearch.test.ElasticsearchTestCase;
+import org.elasticsearch.test.rest.spec.RestApiParser;
+import org.junit.Test;
+
+import java.io.IOException;
+
+import static org.hamcrest.Matchers.containsString;
+
+/**
+ *
+ */
+public class RestApiParserFailingTests extends ElasticsearchTestCase {
+
+    @Test
+    public void brokenSpecShouldThrowUsefulExceptionWhenParsingFailsOnParams() throws Exception {
+        parseAndExpectFailure(BROKEN_SPEC_PARAMS, "Expected params field in rest api definition to contain an object");
+    }
+
+    @Test
+    public void brokenSpecShouldThrowUsefulExceptionWhenParsingFailsOnParts() throws Exception {
+        parseAndExpectFailure(BROKEN_SPEC_PARTS, "Expected parts field in rest api definition to contain an object");
+    }
+
+    private void parseAndExpectFailure(String brokenJson, String expectedErrorMessage) throws Exception {
+        XContentParser parser = JsonXContent.jsonXContent.createParser(brokenJson);
+        try {
+            new RestApiParser().parse(parser);
+            fail("Expected to fail parsing but did not happen");
+        } catch (IOException e) {
+            assertThat(e.getMessage(), containsString(expectedErrorMessage));
+        }
+
+    }
+
+    // see params section is broken, an inside param is missing
+    private static final String BROKEN_SPEC_PARAMS = "{\n" +
+            "  \"ping\": {" +
+            "    \"documentation\": \"http://www.elasticsearch.org/guide/\"," +
+            "    \"methods\": [\"HEAD\"]," +
+            "    \"url\": {" +
+            "      \"path\": \"/\"," +
+            "      \"paths\": [\"/\"]," +
+            "      \"parts\": {" +
+            "      }," +
+            "      \"params\": {" +
+            "        \"type\" : \"boolean\",\n" +
+            "        \"description\" : \"Whether specified concrete indices should be ignored when unavailable (missing or closed)\"\n" +
+            "      }" +
+            "    }," +
+            "    \"body\": null" +
+            "  }" +
+            "}";
+
+    // see parts section is broken, an inside param is missing
+    private static final String BROKEN_SPEC_PARTS = "{\n" +
+            "  \"ping\": {" +
+            "    \"documentation\": \"http://www.elasticsearch.org/guide/\"," +
+            "    \"methods\": [\"HEAD\"]," +
+            "    \"url\": {" +
+            "      \"path\": \"/\"," +
+            "      \"paths\": [\"/\"]," +
+            "      \"parts\": {" +
+            "          \"type\" : \"boolean\",\n" +
+            "      }," +
+            "      \"params\": {\n" +
+            "        \"ignore_unavailable\": {\n" +
+            "          \"type\" : \"boolean\",\n" +
+            "          \"description\" : \"Whether specified concrete indices should be ignored when unavailable (missing or closed)\"\n" +
+            "        } \n" +
+            "    }," +
+            "    \"body\": null" +
+            "  }" +
+            "}";
+
+}