NIRCam WFSS Known Issues

Known issues specific to NIRCam wide field slitless spectroscopy (WFSS) data processing in the JWST Science Calibration Pipeline are described in this article. This is not intended as a how-to guide or as full documentation of individual pipeline steps, but rather to give a scientist-level overview of issues that users should be aware of for their science. 

On this page

Specific artifacts are described in the Artifacts section below. Guidance on using the pipeline data products is provided in the Pipeline Notes section along with a summary of some common issues and workarounds in the summary section.

Please also refer to NIRCam WFSS and Grism Calibration Status for an overview of the current astrometric, photometric, and target acquisition accuracy of NIRCam WFSS/grism data products.


Information on general NIRCam instrument artifacts are found on the main NIRCam Known Issues article.

Tadpoles are artifacts in NIRCam WFSS data that may be mistaken for emission line galaxies. They are most prominent and ubiquitous in grism C module B data.

Shells are fainter WFSS artifacts that appear occasionally due to scattered light from very bright sources.

Pipeline notes

The topics below affect wide field slitless spectroscopy observations and reflect common questions about how to improve the quality of the data from the pipeline. For issues that affect all observing modes, see NIRCam Known Issues.

Background subtraction

Words in bold are GUI menus/
panels or data software packages; 
bold italics are buttons in GUI
tools or package parameters.

Background subtraction is the second step of the calwebb_spec2 stage of the JWST Science Calibration Pipeline. This step relies on a single master background (in the form of a reference file), which will be updated with Cycle 1 observations, and assumes that the WFSS background does not vary in time (during an exposure) and its spectrum is constant. This can be a limiting factor in the case of low signal-to-noise observations. As a mitigation strategy, the user can perform a local background subtraction on the extracted 2-D spectra before extracting the 1-D spectra.

Contamination modeling

One of the main challenges in the spectral extraction for WFSS modes on JWST is the contamination of any individual spectrum by the overlapping spectra of nearby sources. The JWST calibration pipeline is best suited for sparse fields where traces do not overlap and the extraction of 2-D and 1-D spectra is robust. However, observed fields are often crowded. Both NIRISS and NIRCam have grisms that disperse light in 2 orthogonal directions, which could be used to help mitigate some of the spectral overlaps. This is because a spectrum strongly contaminated in one spectral direction might not be as contaminated in the other spectral direction. As fainter magnitudes are reached, however, spectral contamination occurs in any direction and, moreover, being able to correct all spectra for contamination before combining them would allow for the full depth of the data to be used.

The JWST calibration pipeline includes an option to provide a first-order correction for contamination with the wfss_contam step. Briefly, source fluxes from a direct image of the field are used to simulate grism spectra for each source. Each source spectrum is then corrected for contamination by subtracting the simulated spectra of nearby sources. More details are provided on the calibration pipeline documentation. The WFSS contamination correction is not performed by default, but it can be enabled when calling calwebb_spec2 as in this example:

from jwst.pipeline import Spec2Pipeline
spec2 = Spec2Pipeline()
spec2.wfss_contam.skip = False

This contamination model provides a first-order correction in the extraction of overlapping spectra, but it is based on single-band photometry (i.e., it does not account for flux variations within a photometric band) and it depends on the depth of the segmentation map created from the direct image during calwebb_image3 processing. Also, some discrepancies have been observed between the modeling and the simulated spectra. Updates to the wfss_contam step will be guided by experience with data obtained on-orbit. Pirzkal et al. (2017) provides more information about contamination modeling for wide field slitless spectra.

Source identification

It may not be clear which object in your direct image is responsible for a particular trace/emission line in the dispersed spectra. The easiest way to determine coordinates in the dispersed or direct imaging data is to use the gWCS that is built into the calibrated files. Using some of the tools in the calibration pipeline package, you can transform from dispersed to direct coordinates or vice versa.

See the assign_wcs documentation for a basic WFSS example. For a more in-depth example, the pipeline products notebook from the recent JWebbinar is also useful.

Summary of common issues and workarounds

The sections above provide detail on each of the known issues affecting NIRCam coronagraphic data; the table below summarizes some of the most likely issues users may encounter along with any workarounds if available. Note that greyed-out issues have been retired, and are fixed as of the indicated pipeline build.

SymptomsCauseWorkaroundFix buildMitigation Plan
NC-WFSS01: Adjacent sources are included in extracted spectra.This occurs in crowded fields with overlapping spectral traces. 

No workaround is available yet. The calwebb_spec2 pipeline includes an option to provide a first-order correction for source contamination with the wfss_contam step, but some discrepancies and issues are still being investigated.


Updated issue

Implement the wfss_contam step in calwebb_spec2. Work on this is ongoing and is planned for completion in 2024. 

NC-WFSS02: The fluxes of some spectra in the field appear to be too low or even negative.This is caused by over-subtraction of the background. The background subtraction step in calwebb_spec2 assumes the background is constant and does not vary in time, which can be a limiting factor for low signal-to-noise observations.

Users can manually perform a local background subtraction on extracted 2-D spectra before the 1-D extraction in calwebb_spec2.


Created issue

A mitigation plan is under development.

NC-WFSS03: The WFSS pipeline has excessive run times when run locally.Processing WFSS exposures can be prohibitively resource intensive on individual machines due to the number of sources in these files.

Adjust the wfss_nbright parameter in the extract_2d step in calwebb_spec2 to limit the number of extracted sources.

Updated Operations Pipeline

Several efficiency improvements have been made at various stages of processing. STScI will continue monitoring issues that get reported.


Pirzkal, N., et al. 2017 ApJ, 846, 84
FIGSFaint Infrared Grism Survey: Description and Data Reduction

Notable updates
Originally published