---
# System prepended metadata

title: First round `ytt` overlay error message guide
tags: [improving-overlay-err-msgs]

---

---
tags: improving-overlay-err-msgs
---

# First round `ytt` overlay error message guide
The purpose of this doc is to enumerate the overlay error messages possibilities and the new desired output for each scenario.

## Overlay errors

### Type mismatch
 
 #### Expected Map but was array
 ##### Current
 ```
 Overlaying (in following order: overlay.yml): 
   Document on line overlay.yml:3: 
     Map item (key 'clients') on line overlay.yml:4: 
       Expected map, but was *yamlmeta.Array
 ```
 ##### New
 ```
 ytt: Error: Overlaying (in order: overlay.yml):
Type mismatch:
  overlay.yml:4 (map item, 'clients') expects a map
   config.yml:2 (map item, 'clients') has an array.
   
overlay.yml:4
 3: ---
 4: clients:
 5:   client1:
 
config.yml:2
 1: ---
 2: clients:
 3: - client1:
 ``` 


### Expects mismatch
#### Not Enough Documents
 ##### Current
 ```
 Overlaying (in following order: overlay.yml): 
   Document on line overlay.yml:3: 
     Expected number of matched nodes to be 2, but was 1 (lines: config.yml:1)
 ```
 ##### New
 ```
 ytt: Error: Overlaying (in order: overlay.yml):
Expected:
  overlay.yml:3 (document, '---') to match    2 item in
   config.yml:1 (document, '---') but matched 1.


overlay.yml:3
 2: #@overlay/match by=overlay.all, expects=2
 3: ---

config.yml:1
 1: ---
 ```
 
#### Too Many Documents
 ##### Current
 ```
 Overlaying (in following order: overlay.yml): 
   Document on line overlay.yml:3: 
     Expected number of matched nodes to be 0, but was 1 (lines: config.yml:1)
 ```
 ##### New
 ```
  ytt: Error: Overlaying (in order: overlay.yml):
Expected:
  overlay.yml:3 (document, '---') to match    0 item in
   config.yml:1 (document, '---') but matched 1.


overlay.yml:3
 2: #@overlay/match by=overlay.all, expects=0
 3: ---

config.yml:1
 1: ---
 ```

#### Not Enough Map Items
 ##### Current
 ```
 Overlaying (in following order: overlay.yml): 
   Document on line overlay.yml:3: 
     Map item (key 'clients') on line overlay.yml:5: 
       Expected number of matched nodes to be 2, but was 1 (lines: config.yml:2)
 ```
 ##### New
 ```
  ytt: Error: Overlaying (in order: overlay.yml):
Expected:
  overlay.yml:5 (map item, 'clients') to match  2 item in
   config.yml:2 (map in 'document') but matched 1.


overlay.yml:5
 3: ---
 4: #@overlay/match by=overlay.all, expects=2
 5: clients: ~
 
config.yml:2
 1: ---
 2: clients:
 ```
 
#### Too Many Map Items
 ##### Current
 ```
 Overlaying (in following order: overlay.yml): 
   Document on line overlay.yml:3: 
     Map item (key 'clients') on line overlay.yml:5: 
       Expected number of matched nodes to be 0, but was 1 (lines: config.yml:2)
 ```
 ##### New
 ```
  ytt: Error: Overlaying (in order: overlay.yml):
Expected:
  overlay.yml:5 (map item, 'clients') to match   0 item in
   config.yml:2 (map in 'document') but matched 1.


overlay.yml:5
 3: ---
 4: #@overlay/match by=overlay.all, expects=0
 5: clients: ~
 
config.yml:2
 1: ---
 2: clients:
 ```
 
#### Not Enough Array Items
 ##### Current
 ```
 Overlaying (in following order: overlay.yml): 
   Document on line overlay.yml:3: 
     Map item (key 'clients') on line overlay.yml:4: 
       Array item on line overlay.yml:6: 
         Expected number of matched nodes to be 3, but was 2 (lines: config.yml:3, config.yml:5)

 ```
 ##### New
 ```
   ytt: Error: Overlaying (in order: overlay.yml):
Expected:
  overlay.yml:6 (array item, 'clients[0]') to match        3 item in
   config.yml:3,5 (array item in 'clients[]') but matched 2.


overlay.yml:6
 3: ---
 4: clients:
 5: #@overlay/match by=overlay.all,expects=3
 6: -
 
config.yml:3,5
 1: ---
 2: clients:
 3: - client1:
 ...
 5: - client2:
 ``` 

#### Too Many Array Items
 ##### Current
 ```
 Overlaying (in following order: overlay.yml): 
   Document on line overlay.yml:3: 
     Map item (key 'clients') on line overlay.yml:4: 
       Array item on line overlay.yml:6: 
         Expected number of matched nodes to be 1, but was 2 (lines: config.yml:3, config.yml:5)
 ```
 ##### New
  ```
   ytt: Error: Overlaying (in order: overlay.yml):
Expected:
  overlay.yml:6 (array item, 'clients[0]') to match        1 item in
   config.yml:3,5 (array item in 'clients[]') but matched 2.


overlay.yml:6
 3: ---
 4: clients:
 5: #@overlay/match by=overlay.all,expects=1
 6: - client1: ~
 
config.yml:3,5
 1: ---
 2: clients:
 3: - client1:
 ...
 5: - client2:
 ``` 

<!--- 
#### Error message name template
 ##### Current
 ```
 ```
 ##### New
 ```
 ``` 
---> 

## Use Cases


### Input

Input for all use-cases is the same:

`config.yml`
```yaml=
---
clients:
- client1:
    secret: blah1
- client2:
    secret: blah2
```

### Expected Map was Array
`overlay.yml`
```yaml=
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all
---
clients:
  client1:
```

### Not Enough Documents

`overlay.yml`
```ymal=
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all, expects=2
---
``` 

### Too Many Documents

`overlay.yml`
```yaml=
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all, expects=0
---
``` 


### Not Enough Map Items

`overlay.yml`
```yaml=
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all
---
#@overlay/match by=overlay.all, expects=2
clients: ~
```

### Too Many Map Items

`overlay.yml`
```yaml=
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all
---
#@overlay/match by=overlay.all, expects=0
clients: ~
```


### Not Enough Array Items

`overlay.yml`
```yaml=
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all
---
clients:
#@overlay/match by=overlay.all,expects=3
-
``` 

### Too Many Array Items

`overlay.yml`
```yaml=
#@ load("@ytt:overlay", "overlay")
#@overlay/match by=overlay.all
---
clients:
#@overlay/match by=overlay.all,expects=1
- client1: ~
``` 